PC 发布 SSR（客户端渲染）文档

1. 前置条件

• Node.js 版本：^20.19.0 || >=22.12.0（建议 20.19.x 或 22.12.x+）
• 包管理器：建议统一使用 npm（仓库有 package-lock.json）
• 服务器：可运行 Node 的 Linux/Windows Server 均可（下文以 Linux 目录举例）

2. 创建并配置生产环境变量 .env.production

项目脚本中已指定：

• npm run build/preview/generate 会读取：.env.production

仓库通常不提交 .env* 文件，请在 Vortmall-Pc/ 根目录手动创建 .env.production。

2.1 .env.production 推荐模板（客户端渲染模式）

# ========== 渲染模式 ==========
# 客户端渲染模式（本篇文档）：0
# 真·SSR：1（见本文“可选：开启 SSR”）
VITE_SSR=0

# ========== API 配置 ==========
# API 前缀（项目代码里会拼成：VITE_API_URL + VITE_API_PREFIX）
VITE_API_PREFIX=/api

# 后端服务地址：
# - 可留空：前端请求将走同源 /api（需要 Nginx/网关把 /api 转发到后端）
# - 或填写：https://api.xxx.com（前端将直连该域名，需后端允许 CORS）
VITE_API_URL=

# 是否启用 Nitro 内置 proxy（由 Node 进程转发 /api/**）：
# - 0：不启用（常见做法：由 Nginx/网关转发 /api）
# - 1：启用（此时必须填写 VITE_API_URL，否则无法拼接 proxy 目标）
VITE_PROXY=0

# ========== 部署子路径 ==========
# 部署在根路径填 /；部署在子目录（如 /mall/）则填 /mall/
VITE_APP_BASE_URL=/

2.2 关键说明（建议看完）

• VITE_SSR、VITE_API_URL、VITE_API_PREFIX、VITE_PROXY、VITE_APP_BASE_URL 都是在 构建时注入，修改后需要 重新 npm run build 才会生效。
• 当 VITE_API_URL 留空时：
  • 代码侧请求通常会变成同源的 /api/...
  • 你需要用 Nginx/网关把站点的 /api 转发到后端 API（推荐）
• 当 VITE_PROXY=1 时：
  • Node（Nitro）会按 nuxt.config.ts 的 routeRules 把 /api/** 转发到 VITE_API_URL/api/**
  • 此模式 必须设置 VITE_API_URL

3. 运行构建命令生成 .output

在 Vortmall-Pc/ 根目录执行：

npm run build

说明：

• 该命令会先执行 node scripts/i18n/export.cjs（多语言导出），再执行 nuxt build --dotenv .env.production --exec
• 构建成功后，会在项目根目录生成 .output/ 目录

4. .output 产物说明

.output/ 目录一般包含（以实际构建结果为准）：

• public/：静态资源
• server/：服务端入口与运行时
• nitro.json：Nitro 构建信息

5. 上传到服务器目录

5.1 推荐部署方式（保留 .output 目录）

将本地的 .output/ 整个目录上传到服务器，例如：

• 服务器部署根目录：/部署的根目录/web/
• 上传后路径：/部署的根目录/web/.output/

5.2 兼容旧习惯方式（仅覆盖 .output 内文件）

如果你的服务器目录结构就是“根目录下直接有 server/、public/、nitro.json”，也可以：

• 将 .output/ 下的所有内容（public/、server/、nitro.json）覆盖到服务器目录

更新前请先确认服务器目标目录，避免粘贴/覆盖到错误路径。

6. 启动 / 重启进程

6.1 直接用 Node 启动

方式 A（推荐：保留 .output 目录）：

node .output/server/index.mjs

方式 B（如果你把 .output 内容直接覆盖到站点根目录）：

node server/index.mjs

Nitro 默认端口通常为 3000；如需修改端口，可在启动前设置 PORT（或按你们的运维规范注入环境变量）。

7. 可选：开启 SSR（真正服务端渲染）

如果你需要开启 SSR，把 .env.production 中：

VITE_SSR=1

然后重新执行：

npm run build

再按第 5、6 节发布/重启即可。

8. 常见问题（发布排障）

8.1 修改了 .env.production 但线上没变化

• 这些变量是 构建时注入，修改后必须重新 npm run build，再上传产物并重启进程。

8.2 页面资源 404 / 路由不对（部署在子目录）

• 检查 VITE_APP_BASE_URL 是否正确（如 /mall/），并重新构建发布。

8.3 接口跨域 / 404

优先推荐两种方案之一：

• 方案 A（推荐）：VITE_API_URL 留空，前端请求走同源 /api，由 Nginx/网关转发到后端
• 方案 B：填写 VITE_API_URL=https://api.xxx.com 直连后端，并确保后端允许 CORS