前端

nuxt部署

将 Nuxt 3 应用部署到 Nginx 服务器需要经过以下关键步骤，根据渲染模式不同（SSR/SSG/混合模式）配置有所差异：

一、准备工作

  1. 构建生产环境应用

    1
    2
    3
    4
    5
    6
    # 安装依赖
    npm install

    # 根据渲染模式选择构建命令：
    npx nuxi build       # SSR 模式（默认）
    npx nuxi generate    # SSG 静态站点模式

  2. 获取部署文件

    • 构建后生成 .output 目录
    • 关键内容：
      1
      2
      3
      4
      5
      6
      .output/
      ├── public/          # 静态资源 (SSG/静态文件)
      └── server/          # SSR 服务端代码
          ├── index.mjs    # 入口文件
          ├── node_modules/
          └── ...

二、部署方案（按渲染模式）

方案 A：SSR 服务端渲染（推荐）

  1. 上传文件到服务器

    1
    scp -r .output user@server:/path/to/your-project

  2. 安装生产依赖 (在服务器操作)

    1
    2
    3
    4
    5
    # 进入项目目录
    cd /path/to/your-project/.output/server

    # 安装依赖 (仅需运行一次)
    npm install --production

  3. 使用 PM2 管理进程

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    # 全局安装 PM2
    npm install -g pm2

    # 创建启动脚本 ecosystem.config.js
    module.exports = {
      apps: [
        {
          name: 'nuxt-app',
          exec_mode: 'cluster',
          instances: 'max', // 按 CPU 核心数自动扩展
          script: './index.mjs',
          env: {
            NITRO_PORT: 3000,       // 服务端口
            NODE_ENV: 'production',
          }
        }
      ]
    }

    # 启动应用
    pm2 start ecosystem.config.js

  4. 配置 Nginx 反向代理

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    server {
      listen 80;
      server_name your-domain.com;

      # 静态资源直接由 Nginx 处理
      location /_nuxt/ {
        alias /path/to/your-project/.output/public/_nuxt/;
        expires 365d;
      }

      # 其他请求转发到 Nuxt 服务
      location / {
        proxy_pass http://localhost:3000; # 与 PM2 端口一致
        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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
      }
    }

方案 B：SSG 静态站点部署

  1. 获取静态文件

    1
    2
    npx nuxi generate
    # 生成内容在 .output/public 目录

  2. 上传文件到 Nginx

    1
    scp -r .output/public/* user@server:/var/www/your-site

  3. Nginx 配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    server {
      listen 80;
      server_name your-domain.com;
      root /var/www/your-site;
      index index.html;

      # 启用 gzip 压缩
      gzip on;
      gzip_types text/plain application/xml text/css application/javascript;

      # 路由支持 (Vue Router history 模式)
      location / {
        try_files $uri $uri/ /index.html;
      }

      # 缓存静态资源
      location /_nuxt/ {
        expires 365d;
        add_header Cache-Control "public";
      }
    }

三、通用优化配置

  1. 开启 HTTPS

    1
    2
    3
    4
    # 使用 Let's Encrypt 证书
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

  2. 性能优化

    1
    2
    3
    4
    5
    6
    7
    8
    9
    # 静态资源缓存
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
      expires 365d;
      add_header Cache-Control "public, immutable";
    }

    # 开启 Brotli 压缩
    brotli on;
    brotli_types text/plain text/css application/javascript application/json;

  3. 安全加固

    1
    2
    3
    4
    5
    6
    7
    8
    # 禁止访问敏感文件
    location ~ /\.(env|git) {
      deny all;
    }

    # 安全响应头
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

四、部署后验证

  1. 重启 Nginx：
    1
    sudo nginx -t && sudo systemctl restart nginx
  2. 检查服务状态：
    1
    2
    pm2 list          # 查看 Node 进程
    curl localhost:3000 # 测试后端服务
  3. 访问域名检查：

常见问题解决

  1. 502 Bad Gateway

    • 检查 PM2 是否运行：pm2 list
    • 确认代理端口匹配：proxy_pass http://localhost:3000

  2. 静态资源 404

    • 检查 Nginx 的 alias 路径是否正确
    • 确认构建时 baseURL 配置 (nuxt.config.ts 中的 app.baseURL)

  3. 路由刷新 404 (SSG)

    • 确保 Nginx 配置包含：
      1
      2
      3
      location / {
        try_files $uri $uri/ /index.html;
      }

提示：对于复杂项目，推荐使用 Docker 容器化部署，可参考 Nuxt 官方 Docker 示例：https://nuxt.com/docs/getting-started/deployment#docker