构建部署

本文面向准备把商业版前端部署到目标环境的研发和运维团队。目标不仅是说明 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 = https://www.app.artd.pro
VITE_DROP_CONSOLE = true

每个变量分别控制什么

`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
挂到统一网关下

上线检查清单

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

打开首页后无静态资源 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. 部署到目标环境 ​

上线检查清单 ​

最常见的部署问题 ​

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

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

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

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

部署建议 ​

检查清单 ​