PC 发布 CSR(客户端渲染)
PC 发布 CSR(客户端渲染)文档
1. 前置说明(重要)
- CSR 开关:本项目在
nuxt.config.ts中通过VITE_SSR控制是否 SSR:VITE_SSR=1:启用 SSRVITE_SSR=0:CSR(本文档目标)
- 产物目录:执行
npm run generate后会生成.output/,静态资源在.output/public/。 - 部署目录(示例):把
.output/public/下的内容覆盖到服务器:# /部署的根目录/public/pc/
如果你的线上访问路径不是
/pc/(例如挂载在/或/mall/pc/),请务必同步调整VITE_APP_BASE_URL,否则会出现资源 404 或空白页。
2. 打开 .env.production 配置生产环境变量
说明:仓库默认不提交 .env* 文件,请在 Vortmall-Pc/ 根目录手动创建 .env.production。
建议模板(可直接复制,根据实际环境修改):
# .env.production
# 后端地址:
# - 可以为空:此时前端会以“同域名”访问(如请求 /api/**),通常配合 Nginx 做 /api 反向代理
# - 也可以写完整域名:如 https://api.xxx.com
VITE_API_URL=
# API 前缀(默认 /api)
VITE_API_PREFIX=/api
# 是否开启 Nitro 代理(仅对本地/同源转发有意义;生产一般用 Nginx/网关处理)
VITE_PROXY=0
# 关键:CSR 模式(关闭 SSR)
VITE_SSR=0
# 关键:部署子路径(必须与线上静态目录的访问路径一致)
# - 若网站访问为:https://domain.com/pc/ 则填:/pc/
# - 若网站访问为:https://domain.com/ 则填:/
VITE_APP_BASE_URL=/pc/
3. 运行命令编译静态文件
在 Vortmall-Pc/ 根目录执行:
npm run generate
运行成功后会生成目录:
.output/public/(最终需要发布到服务器的静态文件目录)
4. 更新到服务器
将 .output/public/ 下面的所有文件,覆盖到服务器目录(示例):
# /部署的根目录/public/pc/
更新前请先确认服务器目录位置,避免覆盖到错误目录(尤其是把 pc/ 覆盖成 public/ 根目录)。
5. 服务器配置要点(防止刷新 404)
CSR(SPA)通常需要“History 路由回退”:当用户访问 /pc/some/path 或刷新时,服务器应返回 index.html,让前端路由接管。
如果你们使用 Nginx,典型配置要点如下(按实际路径调整):
# 仅示例:请按你们的 root/alias 与域名实际情况调整
location /pc/ {
# 如果是 root 方式:
# root /部署的根目录/public;
# 如果是 alias 方式(更常见于子目录挂载):
alias /部署的根目录/public/pc/;
try_files $uri $uri/ /pc/index.html;
}
6. 常见问题(排障速查)
6.1 页面空白 / 资源 404
- 检查
.env.production的VITE_APP_BASE_URL是否与线上访问路径一致(例如/pc/)。 - 检查服务器实际部署目录是否正确:是否把
.output/public的内容放到了.../public/pc/。
6.2 刷新页面 404(只有首页能打开)
- 服务器缺少 SPA 回退配置(参考上面的
try_files ... /pc/index.html)。
6.3 接口请求失败(跨域 / 404 / 502)
- 若
VITE_API_URL为空:前端会请求同源/api/**,需要网关/Nginx 将/api代理到后端。 - 若
VITE_API_URL为后端域名:需要后端允许 CORS,或统一走网关同源代理。







