# 前端构建

:::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+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 格式的二维数组，每个元素 `[前缀, 目标地址]`：

```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+NaiveUI版',
    VITE_GLOB_API_URL: '',
    VITE_GLOB_API_URL_PREFIX: '/api',
    VITE_GLOB_FILE_URL: 'http://file.flask.naivevue',
};
```

## 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` 实现运行时配置。