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 (推荐)

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

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)

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

# 构建 Nuxt 4 项目
pnpm build

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

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 # 备份/传输包