Nuxt 4 生产环境部署指南涵盖 Linux 环境下 SSR 项目的完整流程。包括 Node.js 版本要求、PM2 进程管理配置、环境变量注入方法。详细说明了 Nginx 动静分离及 API 转发配置，提供自动化部署脚本示例。包含 CentOS 下 SELinux 导致的 502 错误排查、静态资源权限问题处理、PM2 日志查看以及 Certbot HTTPS 证书配置方案。旨在帮助开发者实现稳定高效的 Nuxt 应用上线。
本指南适用于 Nuxt 4 项目在 Linux (CentOS/Ubuntu) 环境下的 SSR（服务端渲染）部署。
Nuxt 4 默认使用 Nitro 引擎。部署前需区分 SSR 端调用 和 浏览器端调用。
在项目根目录创建或编辑此文件，通过环境变量注入配置：
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。
在开发机器执行，确保构建产物是最新的：
# 构建 Nuxt 4 项目
pnpm build
# 压缩打包产物 (减少传输时间)
tar -czf release.tar.gz .output ecosystem.config.cjs
将压缩包上传到服务器 /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
首次部署需安装 PM2 并启动：
# 全局安装 PM2
npm install -g pm2
# 启动应用
pm2 start ecosystem.config.cjs
# 设置开机自启
pm2 startup
pm2 save
针对 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，实现一键发布：
#!/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 上，SELinux 默认禁止 Nginx 连接本地端口。
# 检查是否因为权限被拦
sudo getsebool httpd_can_network_connect
# 开启权限
sudo setsebool -P httpd_can_network_connect 1
确保 Nginx 用户（通常是 nginx 或 www-data）对项目目录有读取权限。
sudo chmod -R 755 /var/www/nuxt-app
如果应用运行不正常，通过日志定位：
pm2 logs nuxt-app --lines 100
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 # 备份/传输包
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online