)
本指南适用于 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 项目pnpmbuild# 压缩打包产物 (减少传输时间)tar-czf release.tar.gz .output ecosystem.config.cjs2. 上传与解压 (Server)
将压缩包上传到服务器/var/www/nuxt-app目录：
# 示例：使用 scp 上传scprelease.tar.gz user@your-server-ip:/var/www/nuxt-app/# 登录服务器解压cd/var/www/nuxt-apptar-xzf release.tar.gz3. 启动应用 (PM2)
首次部署需安装 PM2 并启动：
# 全局安装 PM2npminstall-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"🚀 开始构建..."pnpmbuildecho"📦 正在打包..."tar-czf release.tar.gz .output ecosystem.config.cjsecho"📤 上传服务器..."scprelease.tar.gz$SERVER_USER@$SERVER_IP:$DEPLOY_PATHecho"🔄 重启服务..."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 连接本地端口。
# 检查是否因为权限被拦sudogetsebool httpd_can_network_connect# 开启权限sudosetsebool -P httpd_can_network_connect12. 静态资源 403 Forbidden
确保 Nginx 用户（通常是nginx或www-data）对项目目录有读取权限。
sudochmod-R755/var/www/nuxt-app3. PM2 日志查看
如果应用运行不正常，通过日志定位：
pm2 logs nuxt-app --lines100🔒 HTTPS 配置 (使用 Certbot)
sudodnfinstallcertbot python3-certbot-nginxsudocertbot --nginx -d yourdomain.com📂 目录结构参考
/var/www/nuxt-app/ ├── .output/ # 构建产物 (SSR 入口 & 静态资源) │ ├── server/ # Nitro Server 逻辑 │ └── public/ # 浏览器访问的静态文件 ├── ecosystem.config.cjs # PM2 配置文件 └── release.tar.gz # 备份/传输包
