前端构建

说明

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

# 单个代理
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+ElementPlus版',
    VITE_GLOB_API_URL: '',
    VITE_GLOB_API_URL_PREFIX: '/api',
    VITE_GLOB_FILE_URL: 'http://file.flask.elevue',
};

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