Nuxt 3 部署上线完整流程与常见坑

# Nuxt 3 部署上线完整流程与常见坑 ## 前言 Nuxt 3 开发体验很好，但部署上线时很多人会卡在"本地正常、服务器报错"的环节。本文梳理 Nuxt 3 从构建到部署的完整流程，附常见报错排查。 ## 第一步：确认渲染模式 Nuxt 3 支持多种渲染模式，部署前先明确用哪种： ```javascript // nuxt.config.ts export default defineNuxtConfig({ // SSR：服务端渲染（默认），需要 Node 服务器 // ssr: true, // SSG：静态站点，部署到任意静态托管 // ssr: false, // 或 nuxi generate }); ``` 选择依据： - 内容动态、需要 SEO 实时 → SSR - 内容固定、纯展示 → SSG - 内部系统、不需要 SEO → SPA（ssr: false） ## 第二步：构建 ```bash # 安装依赖 npm install # 构建（SSR 模式） npm run build # 静态生成（SSG 模式） npx nuxi generate ``` 构建产物： - `.output/` 目录是 SSR 的运行目录 - `.output/public/` 是静态资源 - 生成 `.output/server/index.mjs` 入口文件 ## 第三步：部署 Node 服务 ### 用 PM2 运行 ```bash npm install -g pm2 # 启动（.output/server/index.mjs） pm2 start .output/server/index.mjs --name nuxt-app # 或直接 node 运行 node .output/server/index.mjs ``` 默认端口 3000，可用环境变量修改： ```bash PORT=3000 NODE_ENV=production node .output/server/index.mjs ``` ## 第四步：Nginx 反向代理 ```nginx server { listen 80; server_name example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 静态资源直接由 Nginx 提供 location /_nuxt/ { alias /var/www/app/.output/public/_nuxt/; expires 30d; add_header Cache-Control "public, immutable"; } } ``` ## 第五步：环境变量 Nuxt 3 运行时读取 `.env` 文件（通过 runtimeConfig）： ```javascript // nuxt.config.ts export default defineNuxtConfig({ runtimeConfig: { apiSecret: "", // 服务端专用 public: { apiBase: "", // 客户端可见 }, }, }); ``` ```bash # .env（服务器上） NUXT_API_SECRET=xxx NUXT_PUBLIC_API_BASE=https://api.example.com ``` 注意：`NUXT_` 前缀，public 配置用 `NUXT_PUBLIC_`。 ## 常见坑与排查 ### 坑1：构建后内存溢出 大项目构建时内存不足： ```bash NODE_OPTIONS="--max-old-space-size=4096" npm run build ``` ### 坑2：502 Bad Gateway 通常是 Node 服务没起来或端口不对，检查： ```bash pm2 status pm2 logs nuxt-app # 确认端口监听 ss -tunlp | grep 3000 ``` ### 坑3：静态资源 404 Nginx 的 alias 路径要和实际 `.output/public/` 对应，注意结尾斜杠。 ### 坑4：环境变量不生效 `.env` 只在构建时读取，改了要重新 build；运行时变量用 `NUXT_` 前缀的环境变量。 ## 部署检查清单 - [ ] 确认渲染模式（SSR/SSG/SPA） - [ ] 构建成功，产物完整 - [ ] PM2 服务正常运行 - [ ] Nginx 反向代理配置正确 - [ ] 环境变量正确加载 - [ ] 静态资源缓存生效 ## 小结 Nuxt 3 部署的核心：明确渲染模式、正确构建、Node 服务跑起来、Nginx 转发。记住 `.output/` 是运行目录，环境变量用 `NUXT_` 前缀，静态资源交给 Nginx 直接服务，性能更好。