签入版本

2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
@@ -0,0 +1,390 @@
+# 9.3 环境与构建配置
+
+:::tip 概述
+本节说明前端项目的环境变量配置和 Vite 构建配置，包括开发环境和生产环境的差异配置。前端通过 `.env` 文件管理环境变量，Vite 自动根据模式加载对应的 `.env` 文件。
+:::
+
+## 环境变量文件
+
+```text
+ui/
+├── .env                    # 所有环境通用配置
+├── .env.development        # 开发环境配置
+├── .env.production         # 生产环境配置
+└── .env.local              # 本地覆盖（不提交 git）
+```
+
+**加载优先级：** `.env.local` > `.env.{mode}` > `.env`
+
+## 开发环境配置
+
+### `.env.development`
+
+```bash
+# 开发服务器端口
+VITE_PORT = 8001
+
+# 公共基础路径（通常为 /）
+VITE_PUBLIC_PATH = /
+
+# API 接口基础路径（留空，由代理处理）
+VITE_GLOB_API_URL =
+
+# API 前缀（所有接口路径的前缀）
+VITE_GLOB_API_URL_PREFIX = /api
+
+# 代理配置（JSON 数组格式：[["前缀","目标地址"]]）
+VITE_PROXY = [["/api","http://admin.thinkphp6.elevue/api"]]
+
+# 上传接口地址
+VITE_GLOB_UPLOAD_URL = /api/upload
+
+# 图片访问地址（用于预览上传的图片）
+VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue
+
+# 是否在生产环境删除 console（开发环境保留）
+VITE_DROP_CONSOLE = false
+
+# 是否启用 Mock 数据（false = 使用真实后端 API）
+VITE_USE_MOCK = false
+```
+
+## 生产环境配置
+
+### `.env.production`
+
+```bash
+# 公共基础路径（通常为 /，如部署到子目录则设为 /subdir/）
+VITE_PUBLIC_PATH = /
+
+# API 接口基础路径（留空，由 Nginx 代理处理）
+VITE_GLOB_API_URL =
+
+# API 前缀
+VITE_GLOB_API_URL_PREFIX = /api
+
+# 上传接口地址
+VITE_GLOB_UPLOAD_URL = /api/upload
+
+# 图片访问地址（生产环境使用正式域名）
+VITE_GLOB_IMG_URL = https://cdn.example.com
+
+# 是否在生产环境删除 console
+VITE_DROP_CONSOLE = true
+
+# 是否启用 gzip 压缩
+VITE_BUILD_COMPRESS = gzip
+
+# 压缩后是否删除原文件
+VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
+```
+
+## 环境变量详解
+
+### VITE_PORT — 开发服务器端口
+
+```bash
+VITE_PORT = 8001
+```
+
+| 环境 | 值 | 说明 |
+|------|-----|------|
+| 开发 | `8001` | 前端开发服务器端口 |
+| 生产 | 不生效 | 生产环境由 Nginx 提供服务 |
+
+### VITE_PUBLIC_PATH — 公共基础路径
+
+```bash
+VITE_PUBLIC_PATH = /
+```
+
+| 场景 | 值 | 说明 |
+|------|-----|------|
+| 根目录部署 | `/` | 默认值 |
+| 子目录部署 | `/admin/` | 如 `https://example.com/admin/` |
+
+### VITE_GLOB_API_URL — API 基础路径
+
+```bash
+VITE_GLOB_API_URL =
+```
+
+| 场景 | 值 | 说明 |
+|------|-----|------|
+| 开发（代理） | 留空 | 由 Vite proxy 转发 |
+| 生产（同域） | 留空 | 由 Nginx 代理 |
+| 生产（跨域） | `https://api.example.com` | 直接请求后端域名 |
+
+### VITE_PROXY — 开发代理配置
+
+```bash
+VITE_PROXY = [["/api","http://admin.thinkphp6.elevue/api"]]
+```
+
+**格式：** JSON 数组，每项为 `[前缀, 目标地址]`
+
+**作用：** 将前端 `/api/*` 请求代理到后端地址，解决开发环境跨域问题。
+
+**多代理示例：**
+
+```bash
+VITE_PROXY = [["/api","http://localhost:8080/api"],["/upload","http://localhost:8080/upload"]]
+```
+
+### VITE_GLOB_API_URL_PREFIX — API 前缀
+
+```bash
+VITE_GLOB_API_URL_PREFIX = /api
+```
+
+所有 API 请求路径的前缀，与后端路由前缀一致。
+
+### VITE_GLOB_UPLOAD_URL — 上传接口地址
+
+```bash
+VITE_GLOB_UPLOAD_URL = /api/upload
+```
+
+文件上传组件使用的接口地址。
+
+### VITE_GLOB_IMG_URL — 图片访问地址
+
+```bash
+# 开发环境
+VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue
+
+# 生产环境
+VITE_GLOB_IMG_URL = https://cdn.example.com
+```
+
+用于预览上传的图片，拼接图片的完整 URL。
+
+### VITE_DROP_CONSOLE — 删除 console
+
+```bash
+# 开发环境：保留 console（方便调试）
+VITE_DROP_CONSOLE = false
+
+# 生产环境：删除 console（安全+减小体积）
+VITE_DROP_CONSOLE = true
+```
+
+### VITE_BUILD_COMPRESS — Gzip 压缩
+
+```bash
+VITE_BUILD_COMPRESS = gzip
+```
+
+启用 gzip 压缩后，构建产物会生成 `.gz` 文件，Nginx 配置 `gzip_static on` 可直接使用。
+
+## 在代码中访问环境变量
+
+```typescript
+// 读取环境变量（VITE_ 前缀的变量才会暴露给客户端）
+const apiUrl = import.meta.env.VITE_GLOB_API_URL;
+const apiPrefix = import.meta.env.VITE_GLOB_API_URL_PREFIX;
+const uploadUrl = import.meta.env.VITE_GLOB_UPLOAD_URL;
+const imgUrl = import.meta.env.VITE_GLOB_IMG_URL;
+
+// 完整 API 地址
+const fullApiUrl = apiUrl + apiPrefix;  // 如 "/api" 或 "https://api.example.com/api"
+```
+
+:::warning VITE_ 前缀
+只有以 `VITE_` 开头的环境变量才会暴露给客户端代码，其他变量（如 `PORT`）不会被访问到。
+:::
+
+## Vite 配置
+
+### `vite.config.ts`
+
+```typescript
+import { defineConfig, loadEnv } from 'vite';
+
+export default defineConfig(({ mode }) => {
+  // 加载环境变量
+  const env = loadEnv(mode, process.cwd());
+
+  return {
+    // 开发服务器
+    server: {
+      port: Number(env.VITE_PORT) || 8001,
+      proxy: {
+        '/api': {
+          target: 'http://admin.thinkphp6.elevue/api',
+          changeOrigin: true,
+        },
+      },
+    },
+
+    // 构建配置
+    build: {
+      // 生产环境删除 console
+      drop: env.VITE_DROP_CONSOLE === 'true' ? ['console', 'debugger'] : [],
+      // 启用 gzip 压缩
+      rollupOptions: {
+        output: {
+          manualChunks: {
+            vue: ['vue', 'vue-router', 'pinia'],
+            element: ['element-plus'],
+          },
+        },
+      },
+    },
+  };
+});
+```
+
+### 代理配置详解
+
+```typescript
+// 开发环境代理配置
+server: {
+  proxy: {
+    '/api': {
+      target: 'http://admin.thinkphp6.elevue/api',  // 目标地址
+      changeOrigin: true,                            // 修改请求头 Origin
+      rewrite: (path) => path.replace(/^\/api/, ''), // 路径重写（可选）
+    },
+  },
+}
+```
+
+**代理效果：**
+
+```text
+前端请求: GET /api/user/page
+    │
+    ▼ Vite proxy
+    │
+    ▼ 转发到: http://admin.thinkphp6.elevue/api/user/page
+```
+
+## 构建命令
+
+```bash
+# 开发服务器（热更新）
+pnpm dev
+
+# 构建生产版本
+pnpm build
+
+# 预览构建结果（本地启动静态服务器）
+pnpm preview
+
+# ESLint 检查
+pnpm lint:eslint
+
+# ESLint 自动修复
+pnpm lint:eslint --fix
+
+# TypeScript 类型检查
+pnpm type:check
+```
+
+### 构建产物
+
+```text
+ui/dist/
+├── index.html              # 入口文件
+├── assets/
+│   ├── index-xxx.js        # 主 JS（带 hash）
+│   ├── index-xxx.css       # 主 CSS（带 hash）
+│   ├── vue-xxx.js          # Vue 相关（分包）
+│   └── element-xxx.js      # Element Plus（分包）
+├── favicon.ico
+└── static/                 # 静态资源
+```
+
+## 部署配置
+
+### Nginx 配置
+
+```nginx
+server {
+    listen 80;
+    server_name admin.example.com;
+
+    # 前端静态文件
+    root /data/www/admin/dist;
+    index index.html;
+
+    # SPA 路由（所有非文件请求都返回 index.html）
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API 代理到后端
+    location /api/ {
+        proxy_pass http://127.0.0.1:8080/api/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # 静态资源缓存
+    location /assets/ {
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Gzip 压缩
+    gzip on;
+    gzip_static on;  # 优先使用 .gz 文件
+    gzip_types text/css application/javascript application/json;
+}
+```
+
+## 多环境配置
+
+### 测试环境
+
+```bash
+# .env.staging
+VITE_GLOB_API_URL =
+VITE_GLOB_API_URL_PREFIX = /api
+VITE_GLOB_IMG_URL = https://test-cdn.example.com
+VITE_DROP_CONSOLE = true
+```
+
+构建命令：
+
+```bash
+pnpm build --mode staging
+```
+
+### 环境变量对照表
+
+| 变量 | 开发 | 测试 | 生产 |
+|------|------|------|------|
+| `VITE_PORT` | 8001 | - | - |
+| `VITE_GLOB_API_URL` | 留空 | 留空 | 留空 |
+| `VITE_GLOB_API_URL_PREFIX` | /api | /api | /api |
+| `VITE_GLOB_IMG_URL` | http://file.xxx | https://test-cdn.xxx | https://cdn.xxx |
+| `VITE_DROP_CONSOLE` | false | true | true |
+| `VITE_USE_MOCK` | false | false | false |
+
+## 常见问题
+
+### 问题 1：开发环境 API 请求 404
+
+**原因：** 代理配置错误或后端未启动。
+
+**解决：** 检查 `.env.development` 中 `VITE_PROXY` 的目标地址是否正确。
+
+### 问题 2：生产环境 API 请求跨域
+
+**原因：** `VITE_GLOB_API_URL` 配置了跨域地址但后端未配置 CORS。
+
+**解决：** 推荐留空，由 Nginx 代理处理（同域无跨域问题）。
+
+### 问题 3：图片不显示
+
+**原因：** `VITE_GLOB_IMG_URL` 配置错误。
+
+**解决：** 检查图片访问地址是否正确，确保图片 URL 可直接访问。
+
+### 问题 4：构建后体积过大
+
+**原因：** 未启用 gzip 压缩或未分包。
+
+**解决：** 启用 `VITE_BUILD_COMPRESS = gzip`，配置 `manualChunks` 分包。