Nuxt SSR 前端部署

概述

DSMall Pro PC端前端基于 Nuxt 3 框架开发，支持 SSR（服务端渲染）模式。本文档介绍如何在宝塔面板环境下部署 Nuxt SSR 应用。

环境要求

基础环境

Node.js 18.0+ - 宝塔面板软件商店安装
PM2 - Node.js 进程管理器
Nginx 1.20+ - 宝塔面板软件商店安装

部署步骤

1. 安装 Node.js 环境

宝塔面板 → 软件商店 → 运行环境
安装 Node.js 版本管理器
安装 Node.js 18.x 或更高版本

设置 PATH 环境变量（重要）

由于宝塔面板安装的 Node.js 未自动添加到系统 PATH，需要手动设置：

bash

# 1. 查看已安装的 Node.js 版本
ls /www/server/nodejs/
# 输出示例：v22.21.1  （请记录您的版本号）

# 2. 临时设置 PATH（当前终端会话有效）
export PATH=/www/server/nodejs/v22.21.1/bin:$PATH
# 注意：请将 v22.21.1 替换为您实际的版本号

# 3. 验证安装
node -v  # 应显示 v18.x.x 或更高
npm -v   # 应显示版本号

# 4. 永久添加到 PATH（推荐，新开终端也会生效）
echo 'export PATH=/www/server/nodejs/v22.21.1/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

提示：

宝塔面板安装的 Node.js 路径格式为：/www/server/nodejs/v版本号/
即使通过宝塔面板安装了 npm、yarn、pm2，也需要先设置 PATH 才能在终端直接使用
可以通过 ls /www/server/nodejs/ 查看已安装的版本号

2. 安装 PM2 进程管理器

如果已通过宝塔面板安装：

在 软件商店 → 已安装 中确认 PM2 已安装

设置 PATH 后即可使用：

bash

# 先设置 PATH（请替换为您的 Node.js 版本号）
export PATH=/www/server/nodejs/v22.21.1/bin:$PATH

# 验证 PM2
pm2 -v

如果需要手动安装：

bash

# 先设置 PATH
export PATH=/www/server/nodejs/v22.21.1/bin:$PATH

# 安装 PM2
npm install -g pm2

# 验证
pm2 -v

提示：

如果通过宝塔面板已安装 PM2，无需重复安装
只需设置 PATH 环境变量即可使用
建议永久添加到 PATH，方便后续操作

3. 创建网站

在宝塔面板中创建网站，网站目录会自动创建：

宝塔面板 → 网站 → 添加站点
填写域名：www.yourdomain.com（填写您的实际域名）
PHP 版本：纯静态（不需要 PHP）
点击提交

说明：

网站创建后，会自动生成网站目录，例如：/www/wwwroot/www.yourdomain.com/
后续步骤中，项目文件将上传到此目录
如果您的域名是 yourdomain.com，目录可能是 /www/wwwroot/yourdomain.com/，请根据实际情况调整

4. 准备项目文件

方式A：本地构建后上传（推荐）

修改配置文件

编辑 nuxt-consumer/nuxt.config.ts，设置生产环境 API 地址：

typescript

export default defineNuxtConfig({
  compatibilityDate: "2025-07-15",
  devtools: { enabled: false }, // 生产环境关闭
  modules: ["@pinia/nuxt", "@element-plus/nuxt"],
  css: ['~/assets/css/global.css'],
  
  runtimeConfig: {
    public: {
      // 修改为生产环境的 API 地址
      VITE_APP_BASE_URL: 'https://api.yourdomain.com',
      VITE_FILE_BASE_URL: 'https://api.yourdomain.com',
      VITE_FILE_TYPE: 'local', // 或 'oss'
    },
  },
})

本地构建项目

bash

cd nuxt-consumer
npm install
npm run build

上传项目文件
将构建后的 nuxt-consumer 目录下的所有文件上传到网站目录：
- 上传到：/www/wwwroot/www.yourdomain.com/
- 或者使用宝塔文件管理器，将文件上传到网站根目录

方式B：服务器上直接构建

将 nuxt-consumer 目录上传到网站目录：/www/wwwroot/www.yourdomain.com/

在宝塔终端执行：

bash

# 先设置 PATH（如果未永久设置）
export PATH=/www/server/nodejs/v22.21.1/bin:$PATH

cd /www/wwwroot/www.yourdomain.com
npm install
# 修改 nuxt.config.ts 中的 API 地址或创建 .env.production 文件
npm run build

5. 使用 PM2 启动应用

在宝塔终端执行：

bash

# 先设置 PATH（如果未永久设置）
export PATH=/www/server/nodejs/v22.21.1/bin:$PATH

cd /www/wwwroot/www.yourdomain.com
pm2 start .output/server/index.mjs --name nuxt-consumer
pm2 save  # 保存进程列表
pm2 startup  # 设置开机自启（按提示执行生成的命令）

注意：

如果已永久设置 PATH，则无需每次执行 export PATH 命令
请将 www.yourdomain.com 替换为您实际的网站目录名

PM2 常用命令：

bash

pm2 list                    # 查看所有进程
pm2 logs nuxt-consumer      # 查看日志
pm2 restart nuxt-consumer   # 重启应用
pm2 stop nuxt-consumer       # 停止应用
pm2 delete nuxt-consumer     # 删除应用

6. 配置 Nginx 反向代理

配置 Nginx 反向代理

宝塔面板 → 网站 → 找到您的网站 → 设置 → 配置文件
在配置文件中找到 location / 部分，替换为以下完整配置：

nginx

server
{
    listen 80;
    listen 443 ssl;
    listen 443 quic;
    http2 on;
    server_name www.yourdomain.com;
    index index.php index.html index.htm default.php default.htm default.html;
    root /www/wwwroot/www.yourdomain.com;
    
    #CERT-APPLY-CHECK--START
    # 用于SSL证书申请时的文件验证相关配置 -- 请勿删除
    include /www/server/panel/vhost/nginx/well-known/www.yourdomain.com.conf;
    #CERT-APPLY-CHECK--END
    include /www/server/panel/vhost/nginx/extension/www.yourdomain.com/*.conf;
    
    #SSL-START SSL相关配置，请勿删除或修改下一行带注释的404规则
    #error_page 404/404.html;
    ssl_certificate    /www/server/panel/vhost/cert/www.yourdomain.com/fullchain.pem;
    ssl_certificate_key    /www/server/panel/vhost/cert/www.yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_tickets on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";
    add_header Alt-Svc 'quic=":443"; h3=":443"; h3-29=":443"; h3-27=":443";h3-25=":443"; h3-T050=":443"; h3-Q050=":443";h3-Q049=":443";h3-Q048=":443"; h3-Q046=":443"; h3-Q043=":443"';
    error_page 497  https://$host$request_uri;
    #SSL-END

    #ERROR-PAGE-START  错误页配置，可以注释、删除或修改
    error_page 404 /404.html;
    #error_page 502 /502.html;
    #ERROR-PAGE-END

    #禁止访问的文件或目录
    location ~ ^/(\.user.ini|\.htaccess|\.git|\.env|\.svn|\.project|LICENSE|README.md)
    {
        return 404;
    }

    #一键申请SSL证书验证目录相关设置
    location ~ \.well-known{
        allow all;
    }

    #禁止在证书验证目录放入敏感文件
    if ( $uri ~ "^/\.well-known/.*\.(php|jsp|py|js|css|lua|ts|go|zip|tar\.gz|rar|7z|sql|bak)$" ) {
        return 403;
    }

    # 重要：Nuxt 静态资源优先处理（必须在其他 location 之前）
    location /_nuxt/ {
        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;
        
        # 静态资源缓存
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # 其他静态资源（排除 /_nuxt/ 路径）
    location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$
    {
        expires      30d;
        error_log /dev/null;
        access_log /dev/null;
    }

    # JS/CSS 文件（排除 /_nuxt/ 路径）
    location ~ ^(?!/_nuxt/).*\.(js|css)?$
    {
        expires      12h;
        error_log /dev/null;
        access_log /dev/null;
    }

    # Nuxt 应用代理（所有其他请求）
    location / {
        proxy_pass http://127.0.0.1:3000;
        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_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # 超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
        
        # 重要：确保静态资源也能正确代理
        proxy_set_header Accept-Encoding "";
    }

    access_log  /www/wwwlogs/www.yourdomain.com.log;
    error_log  /www/wwwlogs/www.yourdomain.com.error.log;
}

配置说明：

location /_nuxt/：优先处理 Nuxt 静态资源，确保 /_nuxt/ 路径下的 JS/CSS 文件正确代理到 Nuxt 服务器
location ~ ^(?!/_nuxt/).*\.(js|css)?$：处理其他 JS/CSS 文件，但排除 /_nuxt/ 路径，避免冲突
location /：处理所有其他请求，代理到 Nuxt 服务器
SSL 配置已包含在配置中，如果未配置 SSL 证书，相关 SSL 配置会被宝塔面板自动处理

保存并重载 Nginx
- 点击保存
- 点击 重载配置
配置 SSL 证书（可选，推荐）
- 网站 → 设置 → SSL
- 申请 Let's Encrypt 免费证书，或上传您自己的 SSL 证书
- 开启 强制 HTTPS
- 宝塔面板会自动更新 SSL 证书路径到配置文件中

环境变量配置

1. 系统 PATH 环境变量（必须）

宝塔面板安装的 Node.js 需要设置 PATH 才能使用，建议永久添加到系统环境变量：

bash

# 查看已安装的 Node.js 版本
ls /www/server/nodejs/

# 永久添加到 PATH（请替换为您的版本号）
echo 'export PATH=/www/server/nodejs/v22.21.1/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
node -v
npm -v
pm2 -v

全局配置（所有用户生效）：

如果需要所有用户都能使用，可以添加到系统级配置：

bash

# 添加到 /etc/profile（需要 root 权限）
echo 'export PATH=/www/server/nodejs/v22.21.1/bin:$PATH' >> /etc/profile
source /etc/profile

2. Nuxt 应用环境变量（可选）

为了更灵活地管理 Nuxt 应用的配置，可以使用 .env.production 文件：

方式一：使用 .env.production 文件（推荐）

创建环境变量文件

在网站目录下创建 .env.production（例如：/www/wwwroot/www.yourdomain.com/.env.production）：

env

# API 基础地址
NUXT_PUBLIC_VITE_APP_BASE_URL=https://api.yourdomain.com

# 文件访问地址
NUXT_PUBLIC_VITE_FILE_BASE_URL=https://api.yourdomain.com

# 文件类型（local/oss/cos 等）
NUXT_PUBLIC_VITE_FILE_TYPE=local

修改 nuxt.config.ts

typescript

export default defineNuxtConfig({
  compatibilityDate: "2025-07-15",
  devtools: { enabled: false },
  modules: ["@pinia/nuxt", "@element-plus/nuxt"],
  css: ['~/assets/css/global.css'],
  
  runtimeConfig: {
    public: {
      // 从环境变量读取，如果没有则使用默认值
      VITE_APP_BASE_URL: process.env.NUXT_PUBLIC_VITE_APP_BASE_URL || 'http://localhost:3000',
      VITE_FILE_BASE_URL: process.env.NUXT_PUBLIC_VITE_FILE_BASE_URL || 'http://localhost:3000',
      VITE_FILE_TYPE: process.env.NUXT_PUBLIC_VITE_FILE_TYPE || 'local',
    },
  },
})

构建时自动加载
Nuxt 3 会自动加载 .env.production 文件，无需额外配置。

方式二：直接在 nuxt.config.ts 中配置

如果不需要环境变量文件，可以直接在 nuxt.config.ts 中硬编码：

typescript

runtimeConfig: {
  public: {
    VITE_APP_BASE_URL: 'https://api.yourdomain.com',
    VITE_FILE_BASE_URL: 'https://api.yourdomain.com',
    VITE_FILE_TYPE: 'local',
  },
}

方式三：使用系统环境变量

在服务器上设置系统环境变量（适用于多环境部署）：

bash

# 在 ~/.bashrc 或 /etc/profile 中添加
export NUXT_PUBLIC_VITE_APP_BASE_URL=https://api.yourdomain.com
export NUXT_PUBLIC_VITE_FILE_BASE_URL=https://api.yourdomain.com
export NUXT_PUBLIC_VITE_FILE_TYPE=local

# 重新加载配置
source ~/.bashrc
# 或
source /etc/profile

环境变量优先级：

系统环境变量（最高优先级）
.env.production 文件
nuxt.config.ts 中的默认值（最低优先级）

注意事项：

.env.production 文件不要提交到 Git（应添加到 .gitignore）
生产环境建议使用 .env.production 文件，方便管理不同环境的配置
修改环境变量后需要重新构建项目：npm run build

更新部署

当代码更新后，重新部署步骤：

bash

# 1. 设置 PATH（如果未永久设置）
export PATH=/www/server/nodejs/v22.21.1/bin:$PATH

# 2. 停止 PM2 进程
pm2 stop nuxt-consumer

# 3. 更新代码（上传新文件或 git pull）
cd /www/wwwroot/www.yourdomain.com
git pull  # 如果使用 git

# 4. 重新构建
npm install  # 如果有新的依赖
npm run build

# 5. 重启 PM2
pm2 restart nuxt-consumer

验证安装

1. 检查 PM2 进程

bash

pm2 list
# 应该看到 nuxt-consumer 进程状态为 online

2. 检查端口监听

bash

netstat -tlnp | grep 3000
# 应该看到 3000 端口被监听

3. 访问网站

访问 http://www.yourdomain.com 或 https://www.yourdomain.com
检查页面是否正常加载
检查浏览器控制台是否有错误

4. 检查日志

bash

pm2 logs nuxt-consumer --lines 50
# 查看最近 50 行日志，确认没有错误

常见问题

Q1: PM2 启动失败

检查项：

PATH 环境变量是否设置：node -v 和 pm2 -v 是否能正常执行
Node.js 版本是否正确：node -v（需要 18+）
构建是否成功：确认 .output/server/index.mjs 文件存在
查看错误日志：pm2 logs nuxt-consumer

解决方案：

bash

# 1. 先设置 PATH
export PATH=/www/server/nodejs/v22.21.1/bin:$PATH

# 2. 重新构建
cd /www/wwwroot/www.yourdomain.com
npm run build

# 3. 重新启动
pm2 restart nuxt-consumer

Q2: 访问网站显示 502 Bad Gateway

检查项：

PM2 进程是否运行：pm2 list
端口是否被占用：netstat -tlnp | grep 3000
Nginx 配置中的 proxy_pass 地址是否正确

解决方案：

bash

# 检查 PM2 进程
pm2 list

# 如果进程未运行，启动它
pm2 start .output/server/index.mjs --name nuxt-consumer

# 检查 Nginx 配置
nginx -t  # 测试配置是否正确

Q3: 页面显示但 API 请求失败

检查项：

nuxt.config.ts 中的 VITE_APP_BASE_URL 是否正确
后端 API 是否可访问
浏览器控制台的网络请求

解决方案：

修改 nuxt.config.ts 中的 API 地址
重新构建：npm run build
重启 PM2：pm2 restart nuxt-consumer

Q4: 静态资源 404（/_nuxt/ 路径下的 JS/CSS 文件无法加载）

问题现象：

浏览器控制台显示 /_nuxt/*.js 或 /_nuxt/*.css 文件 404 错误
页面显示但样式和脚本无法加载
MIME type 错误：'application/json' is not a supported stylesheet MIME type

原因：

Nginx 配置中 location ~ .*\.(js|css)?$ 规则优先匹配了 /_nuxt/ 路径，导致请求没有代理到 Nuxt 服务器
缺少 location /_nuxt/ 优先处理规则

解决方案：

检查 Nginx 配置
- 确保 location /_nuxt/ 规则在其他 location 规则之前
- 确保 JS/CSS 规则使用 ^(?!/_nuxt/) 排除 /_nuxt/ 路径

检查 PM2 进程

bash

pm2 list
pm2 info nuxt-consumer
# 确认工作目录（cwd）正确

检查文件权限

bash

# 设置文件权限
chown -R www:www /www/wwwroot/www.yourdomain.com
chmod -R 755 /www/wwwroot/www.yourdomain.com

确认 .output/public/_nuxt/ 目录存在

bash

ls -la /www/wwwroot/www.yourdomain.com/.output/public/_nuxt/

如果 PM2 工作目录不对，重新启动

bash

pm2 delete nuxt-consumer
cd /www/wwwroot/www.yourdomain.com
pm2 start .output/server/index.mjs --name nuxt-consumer
pm2 save

查看 Nuxt 服务器日志
bash
```
pm2 logs nuxt-consumer --lines 100
```

Q5: 内存占用过高

解决方案：

检查 PM2 进程：pm2 monit
如果内存持续增长，可以设置 PM2 自动重启：

bash

pm2 start .output/server/index.mjs --name nuxt-consumer --max-memory-restart 500M
pm2 save

部署检查清单

[ ] Node.js 18+ 已安装
[ ] PM2 已安装
[ ] 网站已创建（网站目录已生成）
[ ] 项目文件已上传到网站目录
[ ] 项目已构建（.output 目录存在）
[ ] .output/public/_nuxt/ 目录存在且包含静态资源文件
[ ] PM2 进程正在运行
[ ] PM2 工作目录（cwd）正确
[ ] Nginx 反向代理配置正确
[ ] Nginx 配置中包含 location /_nuxt/ 规则
[ ] 域名解析正确
[ ] SSL 证书已配置（如使用 HTTPS）
[ ] 网站可以正常访问
[ ] 静态资源（/_nuxt/*.js、/_nuxt/*.css）可以正常加载
[ ] API 请求正常

最后更新：2024-01-20
维护者：DSPlatform技术团队(德尚网络)

获取帮助

如果您在使用过程中遇到问题，可以通过以下方式获取帮助：

官方网站：https://www.csdeshang.com
电话咨询：15364080101（微信同号）
QQ咨询：858761000
邮箱咨询：858761000@qq.com
工作时间：工作日 9:00-18:00
微信咨询：扫码添加微信

Nuxt SSR 前端部署 ​

概述 ​

环境要求 ​

基础环境 ​

推荐配置 ​

部署步骤 ​

1. 安装 Node.js 环境 ​

2. 安装 PM2 进程管理器 ​

3. 创建网站 ​

4. 准备项目文件 ​

方式A：本地构建后上传（推荐） ​

方式B：服务器上直接构建 ​

5. 使用 PM2 启动应用 ​

6. 配置 Nginx 反向代理 ​

环境变量配置 ​

1. 系统 PATH 环境变量（必须） ​

2. Nuxt 应用环境变量（可选） ​

方式一：使用 .env.production 文件（推荐） ​

方式二：直接在 nuxt.config.ts 中配置 ​

方式三：使用系统环境变量 ​

更新部署 ​

验证安装 ​

1. 检查 PM2 进程 ​

2. 检查端口监听 ​

3. 访问网站 ​

4. 检查日志 ​

常见问题 ​

Q1: PM2 启动失败 ​

Q2: 访问网站显示 502 Bad Gateway ​

Q3: 页面显示但 API 请求失败 ​

Q4: 静态资源 404（/_nuxt/ 路径下的 JS/CSS 文件无法加载） ​

Q5: 内存占用过高 ​

部署检查清单 ​

获取帮助 ​

Nuxt SSR 前端部署

概述

环境要求

基础环境

推荐配置

部署步骤

1. 安装 Node.js 环境

2. 安装 PM2 进程管理器

3. 创建网站

4. 准备项目文件

方式A：本地构建后上传（推荐）

方式B：服务器上直接构建

5. 使用 PM2 启动应用

6. 配置 Nginx 反向代理

环境变量配置

1. 系统 PATH 环境变量（必须）

2. Nuxt 应用环境变量（可选）

方式一：使用 .env.production 文件（推荐）

方式二：直接在 nuxt.config.ts 中配置

方式三：使用系统环境变量

更新部署

验证安装

1. 检查 PM2 进程

2. 检查端口监听

3. 访问网站

4. 检查日志

常见问题

Q1: PM2 启动失败

Q2: 访问网站显示 502 Bad Gateway

Q3: 页面显示但 API 请求失败

Q4: 静态资源 404（/_nuxt/ 路径下的 JS/CSS 文件无法加载）

Q5: 内存占用过高

部署检查清单

获取帮助