Nuxt 4 生产环境部署指南 (Node.js + Nginx)

本指南适用于 Nuxt 4 项目在 Linux (CentOS/Ubuntu) 环境下的 SSR（服务端渲染）部署。

📋 前置要求

服务器环境

操作系统：Linux (Ubuntu 20.04+ / CentOS 7+ / Debian 11+)
Node.js：>= 20.10.0 (Nuxt 4 强依赖高版本 Node)
Nginx：>= 1.18
PM2：Node.js 进程管理工具
硬件建议：内存 >= 2GB，磁盘 >= 10GB 可用空间

⚙️ 配置 API 地址与环境变量

Nuxt 4 默认使用 Nitro 引擎。部署前需区分 SSR 端调用 和 浏览器端调用。

修改 ecosystem.config.cjs (推荐)

在项目根目录创建或编辑此文件，通过环境变量注入配置：

javascript 复制代码

module.exports = {
  apps: [{
    name: 'nuxt-app',
    port: 3000,
    host: '127.0.0.1',
    script: './.output/server/index.mjs',
    exec_mode: 'cluster', // 开启集群模式
    instances: 'max',      // 根据 CPU 核心数启动实例
    env: {
      NODE_ENV: 'production',
      // SSR 模式下服务器访问后端接口的基准地址
      NUXT_PUBLIC_API_BASE: 'https://api.yourdomain.com', 
    }
  }]
}

注意： NUXT_PUBLIC_API_BASE 对应代码中的 useRuntimeConfig().public.apiBase。

🔧 部署步骤

1. 本地构建 (Local)

在开发机器执行，确保构建产物是最新的：

bash 复制代码

# 构建 Nuxt 4 项目
pnpm build

# 压缩打包产物 (减少传输时间)
tar -czf release.tar.gz .output ecosystem.config.cjs

2. 上传与解压 (Server)

将压缩包上传到服务器 /var/www/nuxt-app 目录：

bash 复制代码

# 示例：使用 scp 上传
scp release.tar.gz user@your-server-ip:/var/www/nuxt-app/

# 登录服务器解压
cd /var/www/nuxt-app
tar -xzf release.tar.gz

3. 启动应用 (PM2)

首次部署需安装 PM2 并启动：

bash 复制代码

# 全局安装 PM2
npm install -g pm2

# 启动应用
pm2 start ecosystem.config.cjs

# 设置开机自启
pm2 startup
pm2 save

🌐 Nginx 核心配置

针对 CentOS/Ubuntu 系统，建议创建独立的配置文件：/etc/nginx/conf.d/nuxt.conf。该配置实现了动静分离 和 API 转发。

nginx 复制代码

# 定义 Node 应用的上游
upstream nuxt_backend {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 80;
    server_name yourdomain.com; # 换成实际域名

    # 1. 静态资源直接由 Nginx 响应 (提升性能)
    # 对应 Nuxt 打包后的 JS/CSS 
    location /_nuxt/ {
        alias /var/www/nuxt-app/.output/public/_nuxt/;
        expires 365d;
        add_header Cache-Control "public, max-age=31536000, immutable";
        access_log off;
    }

    # 2. 业务 API 转发
    # 解决浏览器端访问 /api 时的跨域问题
    location /api/ {
        proxy_pass http://api.internal-server.com/; # 转发到真实后端
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 3. 主程序入口
    location / {
        # 尝试直接读取 public 下的静态文件 (favicon.ico 等)
        root /var/www/nuxt-app/.output/public;
        try_files $uri $uri/ @ssr;
    }

    # 4. SSR 渲染出口
    location @ssr {
        proxy_pass http://nuxt_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
        
        client_max_body_size 20m;
    }
}

🔄 自动化更新脚本 (deploy.sh)

在本地根目录准备 deploy.sh，实现一键发布：

bash 复制代码

#!/bin/bash
# 配置项
SERVER_USER="root"
SERVER_IP="1.2.3.4"
DEPLOY_PATH="/var/www/nuxt-app"

echo "🚀 开始构建..."
pnpm build

echo "📦 正在打包..."
tar -czf release.tar.gz .output ecosystem.config.cjs

echo "📤 上传服务器..."
scp release.tar.gz $SERVER_USER@$SERVER_IP:$DEPLOY_PATH

echo "🔄 重启服务..."
ssh $SERVER_USER@$SERVER_IP "cd $DEPLOY_PATH && tar -xzf release.tar.gz && pm2 reload nuxt-app"

echo "✨ 部署完成！"

⚠️ 常见故障排查 (CentOS 专项)

1. Nginx 502 错误 (SELinux 问题)

在 CentOS 上，SELinux 默认禁止 Nginx 连接本地端口。

bash 复制代码

# 检查是否因为权限被拦
sudo getsebool httpd_can_network_connect
# 开启权限
sudo setsebool -P httpd_can_network_connect 1

2. 静态资源 403 Forbidden

确保 Nginx 用户（通常是 nginx 或 www-data）对项目目录有读取权限。

bash 复制代码

sudo chmod -R 755 /var/www/nuxt-app

3. PM2 日志查看

如果应用运行不正常，通过日志定位：

bash 复制代码

pm2 logs nuxt-app --lines 100

🔒 HTTPS 配置 (使用 Certbot)

bash 复制代码

sudo dnf install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

📂 目录结构参考

text 复制代码

/var/www/nuxt-app/
├── .output/              # 构建产物 (SSR 入口 & 静态资源)
│   ├── server/           # Nitro Server 逻辑
│   └── public/           # 浏览器访问的静态文件
├── ecosystem.config.cjs  # PM2 配置文件
└── release.tar.gz        # 备份/传输包