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

2. 上传与解压 (Server)

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

# 示例：使用 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 并启动：

# 全局安装 PM2
npm install -g pm2
# 启动应用
pm2 start ecosystem.config.cjs
# 设置开机自启
pm2 startup
pm2 save

🌐 Nginx 核心配置

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

# 定义 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，实现一键发布：

#!/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 连接本地端口。

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

2. 静态资源 403 Forbidden

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

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

3. PM2 日志查看

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

pm2 logs nuxt-app --lines 100

🔒 HTTPS 配置 (使用 Certbot)

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

📂 目录结构参考

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