Nuxt3生产环境部署全攻略从环境变量失效到HTTPS配置的终极解决方案当你满怀期待地将开发完成的Nuxt3应用部署到生产环境时可能会遇到一系列惊喜.env变量神秘消失、端口配置无效、HTTPS证书加载失败...这些问题足以让任何开发者抓狂。本文将带你深入Nuxt3部署的核心痛点提供一套经过实战检验的完整解决方案。1. 环境变量失效不只是复制.env那么简单许多开发者误以为只需将开发环境的.env文件复制到服务器就能万事大吉。实际上Nuxt3在生产环境下处理环境变量的方式与开发环境有本质区别。1.1 为什么.env变量会消失Nuxt3使用Nitro服务器进行生产构建而Nitro在打包时会静态分析代码中的环境变量引用。这意味着只有以NITRO_或NUXT_前缀开头的变量会被保留其他变量在构建时会被硬编码或直接丢弃运行时动态读取.env的功能默认关闭// 错误示例这种动态读取在生产环境会失效 const apiUrl process.env.API_URL1.2 官方推荐方案 vs 实际可行方案官方文档建议使用runtimeConfig但这需要提前知道所有可能的变量// nuxt.config.ts export default defineNuxtConfig({ runtimeConfig: { public: { apiUrl: process.env.API_URL || default_value } } })而更实用的方案是强制Nitro在运行时加载.env在项目根目录创建.env文件与开发环境相同修改.output/server/index.mjs在文件顶部添加import { resolve } from node:path import { loadEnvFile } from node:process loadEnvFile(resolve(process.cwd(), ./.env))注意这种方法需要每次部署后手动修改适合中小型项目。对于大型项目建议使用CI/CD流程自动注入环境变量。2. 端口与HTTPS配置超越官方文档的实践Nuxt3默认使用3000端口和HTTP协议这在生产环境显然不够用。以下是经过验证的配置方案。2.1 端口配置的三种方式方法适用场景示例持久性环境变量临时测试NITRO_PORT8080仅当前会话配置文件固定环境nuxt.config.ts中配置永久CLI参数灵活部署node .output/server/index.mjs --port 8080仅当前会话推荐方案在.env中设置NITRO_PORT443 NITRO_HOST0.0.0.02.2 HTTPS配置实战指南启用HTTPS需要三个关键文件SSL证书.crt或.pem私钥文件.key中间证书可选操作步骤在项目根目录创建ssl文件夹将证书文件放入确保权限正确在.env中配置路径NITRO_SSL_CERT./ssl/fullchain.pem NITRO_SSL_KEY./ssl/privkey.key修改.output/server/index.mjs中的服务器创建逻辑const server cert key ? new Server({ key: readFileSync(resolve(process.cwd(), key)), cert: readFileSync(resolve(process.cwd(), cert)), }, toNodeListener(nitroApp.h3App)) : new Server$1(toNodeListener(nitroApp.h3App))提示使用Lets Encrypt证书时fullchain.pem已经包含中间证书无需额外配置。3. PM2高级配置不只是进程守护PM2不仅能保持应用在线还能提供日志轮转、集群模式等高级功能。3.1 基础配置创建ecosystem.config.json{ apps: [{ name: nuxt-app, script: ./server/index.mjs, instances: max, exec_mode: cluster, env: { NODE_ENV: production } }] }3.2 高级功能配置日志管理{ error_file: ./logs/err.log, out_file: ./logs/out.log, log_date_format: YYYY-MM-DD HH:mm:ss, log_rotate: { max_size: 10M, retain: 7, compress: true } }资源监控pm2 monit nuxt-app零停机重启pm2 reload nuxt-app4. 自动化部署告别手动修改每次部署都手动修改index.mjs显然不现实。以下是几种自动化方案4.1 使用部署脚本创建deploy.sh#!/bin/bash # 构建 npm run build # 复制.env和SSL证书 cp .env .output/ cp -r ssl .output/ # 修改index.mjs sed -i 1i\\ import { resolve } from node:path\\ import { loadEnvFile } from node:process\\ loadEnvFile(resolve(process.cwd(), ./.env))\\ .output/server/index.mjs # 启动PM2 pm2 reload ecosystem.config.json4.2 Docker化部署Dockerfile示例FROM node:18 WORKDIR /app COPY .output ./ COPY .env ./ COPY ssl ./ssl/ # 自动注入环境变量加载代码 RUN sed -i 1i\\ import { resolve } from node:path\\ import { loadEnvFile } from node:process\\ loadEnvFile(resolve(process.cwd(), ./.env))\\ ./server/index.mjs EXPOSE 443 CMD [node, ./server/index.mjs]4.3 CI/CD集成GitHub Actions示例name: Deploy Nuxt3 on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - run: npm ci npm run build - run: | sed -i 1i\\ import { resolve } from node:path\\ import { loadEnvFile } from node:process\\ loadEnvFile(resolve(process.cwd(), ./.env))\\ .output/server/index.mjs - uses: appleboy/scp-actionmaster with: host: ${{ secrets.SERVER_HOST }} key: ${{ secrets.SSH_KEY }} source: .output/* target: /var/www/nuxt-app5. 疑难问题排查手册即使按照最佳实践部署仍可能遇到各种问题。以下是常见问题的解决方案5.1 环境变量加载失败症状应用启动但变量值为undefined排查步骤确认.env文件存在且路径正确检查文件权限ls -la .env验证变量前缀是否为NITRO_或NUXT_在index.mjs中添加调试代码console.log(Loaded env:, process.env)5.2 HTTPS证书无效症状浏览器显示不安全警告解决方案确保证书链完整openssl verify -CAfile fullchain.pem cert.crt检查证书有效期openssl x509 -noout -dates -in fullchain.pem验证私钥匹配openssl rsa -noout -modulus -in privkey.key | openssl md5 openssl x509 -noout -modulus -in fullchain.pem | openssl md55.3 PM2应用不断重启可能原因内存泄漏导致OOM未捕获的异常端口冲突排查命令pm2 logs nuxt-app --lines 200 pm2 describe nuxt-app free -h netstat -tulnp | grep 443在多个生产环境部署Nuxt3应用后我发现最稳定的配置组合是使用Docker容器化部署 环境变量通过CI/CD注入 PM2集群模式。这种方案虽然前期配置复杂但后期维护成本极低特别适合需要频繁更新的项目。