签入版本

2026-10-11 19:39:51 +08:00
parent 4084c6bd17
commit 35b8748a68
507 changed files with 147 additions and 56499 deletions
@@ -10,10 +10,8 @@
 ui/
 ├── .env                    # 所有环境通用配置（端口、标题）
 ├── .env.development        # 开发环境（pnpm dev，默认 mode）
-├── .env.production         # 生产构建（pnpm build）
-├── .env.test               # 测试构建（pnpm build:test）
-├── .env.uat                # UAT 构建（pnpm build:uat）
-└── .env.dev                # dev 模式构建（pnpm build:dev）
+├── .env.production         # 生产构建（pnpm build / pnpm build:prod）
+└── .env.test               # 测试构建（pnpm build:test）
 ```

 **加载优先级：** `.env.{mode}` > `.env`（Vite 标准加载规则，可用 `.env.{mode}.local` 做本地覆盖）
@@ -23,41 +21,39 @@ ui/
 ### `.env.development`

 ```bash
-# 开发服务器端口
+# 只在开发模式中被载入
 VITE_PORT = 8001

-# 公共基础路径（通常为 /）
+# 网站根目录
 VITE_PUBLIC_PATH = /

-# 是否启用 Mock 数据（false = 使用真实后端 API）
+# 是否开启mock
 VITE_USE_MOCK = false

-# 是否删除 console（当前项目开发构建同样删除）
+# 网站前缀
+VITE_BASE_URL = /
+
+# 是否删除console
 VITE_DROP_CONSOLE = true

-# 开发代理（JSON 数组格式：[["前缀","目标地址"]]）
+# 跨域代理，可以配置多个，请注意不要换行
 VITE_PROXY=[["/api","http://admin.laravel13.naivevue/api"]]

-# API 接口基础路径（留空，由代理处理）
+# API 接口地址
 VITE_GLOB_API_URL =

-# 上传接口地址（留空，走同域/代理）
-VITE_GLOB_UPLOAD_URL=
+# 图片上传地址
+VITE_GLOB_UPLOAD_URL =

-# 图片前缀地址（留空，按后端返回的地址解析）
-VITE_GLOB_IMG_URL=
+# 图片前缀地址
+VITE_GLOB_IMG_URL =

-# 构建压缩方式：none / gzip / brotli
-VITE_BUILD_COMPRESS = 'none'
-
-VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
-
-# API 前缀（所有接口路径的前缀）
+# 接口前缀
 VITE_GLOB_API_URL_PREFIX = /api
 ```

 :::tip 代理目标地址
-`VITE_PROXY` 当前默认指向 Laragon 虚拟主机 `http://admin.laravel13.naivevue/api`；使用 `php artisan serve` 时改为直连 `http://admin.laravel13.naivevue/api`（见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)）。修改后需重启 `pnpm dev`。
+`VITE_PROXY` 是开发代理的唯一配置来源，当前值指向 Laragon 虚拟主机 `http://admin.laravel13.naivevue/api`（见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)）。修改后需重启 `pnpm dev` 生效。
 :::

 ## 生产环境配置
@@ -65,34 +61,43 @@ VITE_GLOB_API_URL_PREFIX = /api
 ### `.env.production`

 ```bash
-# 是否启用 Mock 数据
+# 是否开启mock
 VITE_USE_MOCK = false

-# 公共基础路径（通常为 /，如部署到子目录则设为 /subdir/）
+# 网站根目录
 VITE_PUBLIC_PATH = /

-# 是否删除 console
+# 网站前缀
+VITE_BASE_URL = /
+
+# 是否删除console
 VITE_DROP_CONSOLE = true

-# API 接口基础路径（留空，由 Nginx 代理处理）
+# API
 VITE_GLOB_API_URL =

-# 上传接口地址（留空，走同域）
-VITE_GLOB_UPLOAD_URL=
+# 图片上传地址
+VITE_GLOB_UPLOAD_URL =

-# 图片前缀地址（留空；跨域部署时配置 CDN/后端域名，与 FILE_DOMAIN_URL 一致）
-VITE_GLOB_IMG_URL=
+# 图片前缀地址
+VITE_GLOB_IMG_URL =

-# API 前缀
+# 接口前缀
 VITE_GLOB_API_URL_PREFIX = /api

-# 构建压缩方式（当前默认 none；可选 gzip / brotli）
+# 是否启用gzip压缩或brotli压缩
+# 可选: gzip | brotli | none
+# 如果你需要多种形式，你可以用','来分隔
 VITE_BUILD_COMPRESS = 'none'

-# 压缩后是否删除原文件
+# 使用压缩时是否删除原始文件，默认为false
 VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
 ```

+:::info 生产环境没有 VITE_PROXY
+`VITE_PROXY` 仅在开发模式由 Vite dev server 使用；生产环境由 Nginx 反向代理 `/api`（见下方部署配置）。
+:::
+
 ## 环境变量详解

 ### VITE_PORT — 开发服务器端口
@@ -120,10 +125,7 @@ VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
 ### VITE_PROXY — 开发代理配置

 ```bash
-# 当前 .env.development 中的值（Laragon 虚拟主机）
-VITE_PROXY=[["/api","http://admin.laravel13.naivevue/api"]]
-
-# 直连 artisan serve 时的写法
+# .env.development 中的值（指向 Laragon 虚拟主机）
 VITE_PROXY=[["/api","http://admin.laravel13.naivevue/api"]]
 ```

@@ -204,25 +206,29 @@ const fullApiUrl = apiUrl + apiPrefix;  // 如 "/api" 或 "https://api.example.c

 ```typescript
 // ui/vite.config.ts（摘自实际代码，节选）
-export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, process.cwd());
-
-  // VITE_PROXY 容错处理：未配置时使用空代理
-  let VITE_PROXY: any = viteEnv.VITE_PROXY;
-  if (!VITE_PROXY) {
-    VITE_PROXY = '[[]]'; // 默认空代理
-  }
-  if (typeof VITE_PROXY === 'string') {
-    VITE_PROXY = JSON.parse(VITE_PROXY);
-  }
+export default ({ command, mode }: ConfigEnv): UserConfig => {
+  const root = process.cwd();
+  const env = loadEnv(mode, root);
+  const viteEnv = wrapperEnv(env);   // VITE_PROXY 在此由字符串 JSON.parse 为数组（见 build/utils.ts）
+  const { VITE_PUBLIC_PATH, VITE_PORT, VITE_GLOB_PROD_MOCK, VITE_PROXY } = viteEnv;

  return {
+    base: VITE_PUBLIC_PATH,
    server: {
-      proxy: createProxy(VITE_PROXY),   // 见 build/vite/proxy.ts
+      host: true,
+      port: VITE_PORT,               // 端口来自 .env.development 的 VITE_PORT
+      proxy: createProxy(VITE_PROXY), // 见 build/vite/proxy.ts
    },
    // ... 插件、路径别名等见 ui/vite.config.ts 全文
  };
-});
+};
+
+// ui/build/utils.ts —— wrapperEnv 中对 VITE_PROXY 做 JSON 解析
+if (envName === 'VITE_PROXY') {
+  try {
+    realName = JSON.parse(realName);
+  } catch (error) {}
+}

 // ui/build/vite/proxy.ts —— 由 [前缀, 目标] 数组生成代理规则
 export function createProxy(list: ProxyList = []) {
@@ -338,23 +344,27 @@ server {

 ## 多环境配置

-### 测试 / UAT 环境（项目实际提供）
+### 测试环境（项目实际提供）

 ```bash
 # .env.test（pnpm build:test）
-VITE_GLOB_API_URL =
-VITE_GLOB_API_URL_PREFIX = /api
+VITE_USE_MOCK = true
+VITE_PUBLIC_PATH = /
+VITE_BASE_URL = /
 VITE_DROP_CONSOLE = true
-
-# .env.uat（pnpm build:uat）同结构，按需调整
+VITE_GLOB_API_URL =
+VITE_GLOB_UPLOAD_URL =
+VITE_GLOB_IMG_URL =
+VITE_GLOB_API_URL_PREFIX = /api
+VITE_BUILD_COMPRESS = 'none'
+VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
 ```

 构建命令（见 `ui/package.json` scripts）：

 ```bash
 pnpm build:test    # 测试环境构建
-pnpm build:uat     # UAT 环境构建
-pnpm build:prod    # 生产环境构建
+pnpm build:prod    # 生产环境构建（与 pnpm build 等价）
 ```

 ### 环境变量对照表
@@ -362,12 +372,13 @@ pnpm build:prod    # 生产环境构建
 | 变量 | 开发 | 测试 | 生产 |
 |------|------|------|------|
 | `VITE_PORT` | 8001 | - | - |
+| `VITE_BASE_URL` | / | / | / |
 | `VITE_GLOB_API_URL` | 留空 | 留空 | 留空 |
 | `VITE_GLOB_API_URL_PREFIX` | /api | /api | /api |
 | `VITE_PROXY` | `[["/api","http://admin.laravel13.naivevue/api"]]` | - | - |
 | `VITE_GLOB_IMG_URL` | 留空 | 留空 | 留空（按需配置 CDN） |
 | `VITE_DROP_CONSOLE` | true | true | true |
-| `VITE_USE_MOCK` | false | false | false |
+| `VITE_USE_MOCK` | false | true | false |

 ## 常见问题