6.4 KiB
6.4 KiB
前端构建
:::tip 说明
前端使用 Vite 构建，支持开发服务器和生产构建。vite.config.ts 通过环境变量和插件系统管理构建配置，生产环境推荐使用 Nginx 部署。
:::
构建架构
vite.config.ts
│
├─ loadEnv(mode) ← 按 mode 加载 .env / .env.{mode}
├─ wrapperEnv() ← 类型转换（string→number/boolean/JSON）
├─ createVitePlugins() ← 组装插件链
├─ createProxy() ← 生成代理配置
│
▼
┌──────────────────────────────────────────────────────┐
│ Vite 构建 │
│ ├─ 开发：vite dev（HMR + proxy） │
│ └─ 生产：vite build → postBuild → app.config.js │
└──────────────────────────────────────────────────────┘
开发环境
# 安装依赖
pnpm install
# 启动开发服务器（HMR 热更新）
pnpm dev
# 等效命令
pnpm serve
开发服务器默认运行在 http://localhost:8001（端口由 VITE_PORT 控制），通过 Vite 代理将 /api 请求转发到后端。
多环境开发命令
| 命令 | mode | 加载的 env 文件 | 说明 |
|---|---|---|---|
pnpm dev |
development |
.env + .env.development |
本地开发（默认） |
环境变量体系
env 文件加载规则
Vite 按 mode 加载环境变量，后面的文件覆盖前面的：
| 文件 | 加载时机 | 说明 |
|---|---|---|
.env |
所有模式 | 通用配置（端口、标题、短名） |
.env.development |
pnpm dev |
开发配置（代理、mock） |
.env.production |
pnpm build |
生产配置 |
.env.test |
pnpm build:test |
测试环境 |
.env.uat |
pnpm build:uat |
UAT 环境 |
.env.dev |
pnpm build:dev |
开发联调环境 |
环境变量完整参考
| 变量 | 类型 | 默认值 | 说明 |
|---|---|---|---|
VITE_PORT |
number |
8001 |
开发服务器端口 |
VITE_PUBLIC_PATH |
string |
/ |
部署基础路径（子目录部署时修改） |
VITE_GLOB_APP_TITLE |
string |
Flask+NaiveUI版 |
应用标题（注入 HTML） |
VITE_GLOB_APP_SHORT_NAME |
string |
Flask+NaiveUI版 |
应用短名（用于生成运行时配置变量名） |
VITE_GLOB_API_URL |
string |
空 | API 基础路径（留空使用相对路径） |
VITE_GLOB_API_URL_PREFIX |
string |
/api |
API 前缀 |
VITE_GLOB_FILE_URL |
string |
- | 文件访问域名（拼接上传文件 URL） |
VITE_GLOB_UPLOAD_URL |
string |
- | 图片上传地址 |
VITE_GLOB_IMG_URL |
string |
- | 图片前缀地址 |
VITE_GLOB_PROD_MOCK |
boolean |
false |
生产环境是否开启 mock |
VITE_USE_MOCK |
boolean |
false |
开发环境是否开启 mock |
VITE_DROP_CONSOLE |
boolean |
true |
构建时删除 console |
VITE_PROXY |
JSON |
[["/api","http://127.0.0.1:8021/api/v1"]] |
跨域代理配置（JSON 数组） |
VITE_BUILD_COMPRESS |
string |
'none' |
压缩方式：gzip / brotli / none |
VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE |
boolean |
false |
压缩后是否删除原文件 |
代理配置格式
VITE_PROXY 是 JSON 格式的二维数组，每个元素 [前缀, 目标地址]：
# 单个代理
VITE_PROXY=[["/api","http://127.0.0.1:8021/api/v1"]]
# 多个代理（注意不要换行）
VITE_PROXY=[["/api","http://127.0.0.1:8021/api/v1"],["/ws","ws://127.0.0.1:8021/ws"]]
代理生成逻辑（build/vite/proxy.ts）：
// 输入: [["/api", "http://127.0.0.1:8021/api/v1"]]
// 输出:
{
'/api': {
target: 'http://127.0.0.1:8021/api/v1',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
生产构建
构建命令
# 生产环境构建
pnpm build
# 指定环境构建
pnpm build:dev # 开发联调环境
pnpm build:test # 测试环境
pnpm build:uat # UAT 环境
构建产物
构建完成后，产物输出到 dist/ 目录：
dist/
├── index.html # 入口 HTML
├── favicon.ico # 图标
├── assets/
│ ├── js/ # JavaScript 文件
│ ├── css/ # CSS 文件
│ └── images/ # 图片资源
└── runtime.config.js # 运行时配置（部署时修改）
运行时配置
runtime.config.js 在构建后生成，部署时可直接修改，无需重新构建：
window['<%- appName %>'] = {
VITE_GLOB_APP_TITLE: 'Flask+NaiveUI版',
VITE_GLOB_API_URL: '',
VITE_GLOB_API_URL_PREFIX: '/api',
VITE_GLOB_FILE_URL: 'http://file.flask.naivevue',
};
Nginx 部署配置
server {
listen 80;
server_name your-domain.com;
# 前端静态文件
root /data/apps/dist;
index index.html;
# 前端路由
location / {
try_files $uri $uri/ /index.html;
}
# 后端 API 反向代理
location /api/ {
proxy_pass http://127.0.0.1:8021/api/;
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;
}
# 上传文件访问
location /api/file/ {
alias /data/apps/uploads/;
expires 30d;
}
# 静态资源缓存
location /assets/ {
expires 30d;
add_header Cache-Control "public, immutable";
}
}
常见问题
代理不生效
1. 检查 VITE_PROXY 格式是否正确（JSON 二维数组）
2. 检查后端是否运行在 http://127.0.0.1:8021
3. 重启开发服务器使配置生效
构建后页面空白
1. 检查 VITE_PUBLIC_PATH 配置
2. 检查 Nginx 是否配置了 try_files
3. 检查浏览器控制台是否有错误
环境变量不生效
1. 确认变量名以 VITE_ 开头
2. 确认 env 文件在正确的位置
3. 重启开发服务器
总结
前端构建使用 Vite，支持开发服务器（HMR 热更新）和生产构建。环境变量通过 .env 文件管理，代理配置通过 VITE_PROXY 设置。生产环境推荐使用 Nginx 部署，配合 runtime.config.js 实现运行时配置。