219 lines
6.4 KiB
Markdown
219 lines
6.4 KiB
Markdown
# 前端构建
|
||
|
||
:::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 │
|
||
└──────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 开发环境
|
||
|
||
```bash
|
||
# 安装依赖
|
||
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+ElementPlus版` | 应用标题（注入 HTML） |
|
||
| `VITE_GLOB_APP_SHORT_NAME` | `string` | `Flask+ElementPlus版` | 应用短名（用于生成运行时配置变量名） |
|
||
| `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 格式的二维数组，每个元素 `[前缀, 目标地址]`：
|
||
|
||
```bash
|
||
# 单个代理
|
||
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`）：
|
||
|
||
```typescript
|
||
// 输入: [["/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/, '')
|
||
}
|
||
}
|
||
```
|
||
|
||
## 生产构建
|
||
|
||
### 构建命令
|
||
|
||
```bash
|
||
# 生产环境构建
|
||
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` 在构建后生成，部署时可直接修改，无需重新构建：
|
||
|
||
```javascript
|
||
window['<%- appName %>'] = {
|
||
VITE_GLOB_APP_TITLE: 'Flask+ElementPlus版',
|
||
VITE_GLOB_API_URL: '',
|
||
VITE_GLOB_API_URL_PREFIX: '/api',
|
||
VITE_GLOB_FILE_URL: 'http://file.flask.elevue',
|
||
};
|
||
```
|
||
|
||
## Nginx 部署配置
|
||
|
||
```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` 实现运行时配置。
|