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 项目pnpmbuild# 压缩打包产物 (减少传输时间)tar-czf release.tar.gz .output ecosystem.config.cjs

2. 上传与解压 (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.gz

3. 启动应用 (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_connect1

2. 静态资源 403 Forbidden

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

sudochmod-R755/var/www/nuxt-app

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