构建部署

本文面向准备把商业版前端部署到目标环境的研发和运维团队。目标不仅是说明 pnpm build，也包括明确哪些配置会影响生产环境的访问、登录和联调。

部署前先确认三件事

1. 前端部署路径

项目是部署在：

根路径 /
还是某个子目录，例如 /admin/

这直接影响 VITE_BASE_URL。

2. 后端访问方式

生产环境是：

前后端分离部署
还是统一走同域网关

这会影响：

VITE_API_URL
Cookie 策略
跨域配置

3. 登录态如何续期

如果生产环境需要依赖 Refresh Token Cookie，必须提前确认：

域名
HTTPS
反向代理
Cookie 策略

关键生产变量

当前 .env.production 中最关键的是：

txt

VITE_BASE_URL = /
VITE_API_URL = /
VITE_DROP_CONSOLE = true

上述示例采用同域网关：静态页面和 /api 使用同一站点，由网关把 API 转发到实际后端。Java 默认本机端口为 13001，Nest.js 默认本机端口为 13000，以部署配置为准。VITE_API_PROXY_URL 仅用于 Vite 开发服务，构建后的静态文件不会自带开发代理。

如果 API 使用独立域名，将 VITE_API_URL 改为客户实际地址，例如 https://api.example.com，并配置对应 CORS 与 Cookie 策略。该地址填写 API 服务的基础地址，不附加重复的 /api/v1，因为接口封装已包含前缀。不要使用官方演示域名连接客户业务。

每个变量分别控制什么

`VITE_BASE_URL`

控制前端静态资源和路由的基础路径。

如果站点部署在根路径，保持 /
如果站点部署在子目录，必须同步改成对应子路径

`VITE_API_URL`

控制生产环境请求的目标后端地址。

前后端分离部署时，通常写完整 API 域名
同域代理时，也可以按你的网关规则改成相对路径

`VITE_DROP_CONSOLE`

控制生产环境是否移除 console 输出。

标准部署流程

1. 修改生产环境配置

确认：

VITE_BASE_URL
VITE_API_URL

2. 构建产物

bash

pnpm build

输出目录为：

txt

dist/

3. 本地预览生产包

bash

pnpm serve

这一步很重要，因为它能提前暴露：

路径错误
资源丢失
API 地址错误

4. 部署到目标环境

常见做法包括：

Nginx 托管静态资源
部署到对象存储/CDN
挂到统一网关下

Java 与 Nest.js 部署差异

前端构建、静态资源托管与路由方式共用，后端部署参数分别维护：

项目	Java 版	Nest.js 版
后端部署配置	交付仓库外置 `config/application-prod.yml`，按 Java README 部署	按 Nest.js 后端部署文档配置
网关目标	实际 Java 服务，默认端口 `13001`	实际 Nest.js 服务，默认端口 `13000`
登录态	保留 Refresh Token Cookie，HTTPS 与代理配置需匹配	保留 Refresh Token Cookie，HTTPS 与代理配置需匹配
流式接口	通知与 AI SSE 关闭代理缓冲，允许长连接	通知与 AI SSE 同样需检查代理缓冲与超时

Java 部署见 Java 部署运维；Nest.js 后端部署文档不作为 Java 的配置步骤。只切换前端 API 地址不会自动部署或配置后端。

Java 文件中心使用 MinIO 时，需先完成前端存储标签与筛选适配，见功能边界。

上线检查清单

上线前建议至少逐条确认：

打开首页后无静态资源 404
登录流程正常
刷新页面后登录状态保持正常
任意菜单页刷新后不会 404
文件上传、下载、预览使用的是正确域名
控制台没有持续性的 401、403、404

最常见的部署问题

问题一：构建后页面空白或资源 404

优先检查 VITE_BASE_URL 是否和部署路径一致。

问题二：生产环境登录成功但刷新后登录状态失效

优先检查：

Cookie 是否写入
域名是否一致
HTTPS 是否开启
代理层是否透传 Cookie

问题三：页面能打开但接口访问失败

优先检查：

VITE_API_URL
后端 CORS
网关转发规则

问题四：某些页面刷新报 404

如果使用 history 路由通常要配额外重写规则；当前项目采用的是 createWebHashHistory()，因此这类问题会少很多，但如果你的网关做了特殊处理，也仍然要关注。

部署建议

进入生产环境前，建议把下面内容写入配置记录：

前端访问域名
后端 API 域名
上传域名
部署路径
是否同域
是否启用 HTTPS

检查清单

前端上线完成后，建议确认：

首页、登录页和关键菜单页在业务域名下可访问。
生产 API 地址、Cookie 策略和后端 CORS 配置匹配。
文件上传、下载、预览使用的域名与部署环境一致。
构建产物来自生产配置，且无持续性的控制台错误。

构建部署 ​

部署前先确认三件事 ​

1. 前端部署路径 ​

2. 后端访问方式 ​

3. 登录态如何续期 ​

关键生产变量 ​

每个变量分别控制什么 ​

VITE_BASE_URL ​

VITE_API_URL ​

VITE_DROP_CONSOLE ​

标准部署流程 ​

1. 修改生产环境配置 ​

2. 构建产物 ​

3. 本地预览生产包 ​

4. 部署到目标环境 ​

Java 与 Nest.js 部署差异 ​

上线检查清单 ​

最常见的部署问题 ​

问题一：构建后页面空白或资源 404 ​

问题二：生产环境登录成功但刷新后登录状态失效 ​

问题三：页面能打开但接口访问失败 ​

问题四：某些页面刷新报 404 ​

部署建议 ​

检查清单 ​