签入版本

2026-10-11 19:06:33 +08:00
parent 17d28de8b7
commit 4084c6bd17
674 changed files with 58855 additions and 1892 deletions
@@ -40,57 +40,79 @@ npm config set registry https://registry.npmmirror.com

 ### `.env.development`（开发环境）

+摘自前端项目 `ui/.env.development`：
+
 ```bash
-# 服务端口
+# 只在开发模式中被载入
 VITE_PORT = 8001

-# 公共基础路径
+# 网站根目录
 VITE_PUBLIC_PATH = /

-# 代理配置（JSON 数组格式：[["前缀","目标地址"]]）
-VITE_PROXY = [["/api","http://localhost:8000/api"]]
+# 是否开启mock
+VITE_USE_MOCK = false

-# API 接口基础路径（留空，由代理处理）
+# 是否删除console
+VITE_DROP_CONSOLE = true
+
+# 跨域代理，可以配置多个，请注意不要换行
+VITE_PROXY=[["/api","http://admin.laravel13.elevue/api"]]
+
+# API 接口地址
 VITE_GLOB_API_URL =

-# API 前缀
+# 图片上传地址
+VITE_GLOB_UPLOAD_URL=
+
+# 图片前缀地址
+VITE_GLOB_IMG_URL=
+# 是否启用gzip压缩或brotli压缩
+# 可选: gzip | brotli | none
+# 如果你需要多种形式，你可以用','来分隔
+VITE_BUILD_COMPRESS = 'none'
+
+# 使用压缩时是否删除原始文件，默认为false
+VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
+# 接口前缀
 VITE_GLOB_API_URL_PREFIX = /api
-
-# 上传接口地址
-VITE_GLOB_UPLOAD_URL = /api/upload
-
-# 图片访问地址（附件域名，对应后端 FILE_DOMAIN_URL）
-VITE_GLOB_IMG_URL = http://file.laravel13.elevue
-
-# 是否启用 Mock 数据（false = 使用真实后端 API）
-VITE_USE_MOCK = false
 ```

+:::tip 代理目标
+`VITE_PROXY` 默认指向 Laragon 虚拟主机 `http://admin.laravel13.elevue/api`（见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)）；直连 `php artisan serve` 时改为 `[["/api","http://admin.laravel13.elevue/api"]]`。修改后需重启 `pnpm dev` 生效。
+:::
+
 ### `.env.production`（生产环境）

+摘自前端项目 `ui/.env.production`：
+
 ```bash
-# 公共基础路径
+# 是否开启mock
+VITE_USE_MOCK = false
+
+# 网站根目录
 VITE_PUBLIC_PATH = /

-# 是否在生产环境删除 console
+# 是否删除console
 VITE_DROP_CONSOLE = true

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

-# API 前缀
+# 图片上传地址
+VITE_GLOB_UPLOAD_URL=
+
+# 图片前缀地址
+VITE_GLOB_IMG_URL=
+
+# 接口前缀
 VITE_GLOB_API_URL_PREFIX = /api

-# 上传接口地址
-VITE_GLOB_UPLOAD_URL = /api/upload
+# 是否启用gzip压缩或brotli压缩
+# 可选: gzip | brotli | none
+# 如果你需要多种形式，你可以用','来分隔
+VITE_BUILD_COMPRESS = 'none'

-# 图片访问地址
-VITE_GLOB_IMG_URL = https://file.example.com
-
-# 是否启用 gzip 压缩
-VITE_BUILD_COMPRESS = gzip
-
-# 压缩后是否删除原文件
+# 使用压缩时是否删除原始文件，默认为false
 VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
 ```

@@ -117,31 +139,33 @@ npm run dev

 ## 步骤四：配置 API 代理

-开发环境下，前端通过 Vite 代理将 `/api` 请求转发到后端服务。
+开发环境下，前端通过 Vite 代理将 `/api` 请求转发到后端服务，代理规则由 `.env.development` 的 `VITE_PROXY` 驱动（并非写死在 `vite.config.ts` 中）。

-在 `vite.config.ts` 中配置代理：
+`vite.config.ts` 读取 `VITE_PROXY` 并调用 `createProxy` 生成代理：

 ```typescript
 // ui/vite.config.ts
 server: {
-  port: 8001,                                // 开发服务器端口（对应 VITE_PORT）
-  proxy: {
-    '/api': {
-      target: 'http://localhost:8000/api',   // 后端服务地址（对应 VITE_PROXY）
-      changeOrigin: true,                     // 开启跨域（修改请求头的 Origin）
-      rewrite: (path) => path,                // 保持路径不变（不做路径替换）
-    },
-  },
+  host: true,
+  port: VITE_PORT,                 // 开发服务器端口（对应 VITE_PORT）
+  proxy: createProxy(VITE_PROXY),  // 由 .env.development 的 VITE_PROXY 生成
 }
 ```

-后端使用虚拟域名时（见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)），target 改为对应地址：
+`createProxy`（`build/vite/proxy.ts`）为每个 `[前缀, 目标地址]` 生成一条代理规则：

 ```typescript
-target: 'http://admin.laravel13.elevue/api',
+ret[prefix] = {
+  target,                          // 目标地址（自带 /api，如 http://admin.laravel13.elevue/api）
+  changeOrigin: true,              // 修改请求头 Origin，解决跨域
+  ws: true,                        // 支持 WebSocket
+  rewrite: (path) => path.replace(new RegExp(`^${prefix}`), ''),  // 去掉 /api 前缀，由 target 中的 /api 补回
+};
 ```

-确保后端服务已启动（`php artisan serve`），然后访问 `http://localhost:8001`。
+更换后端地址时修改 `.env.development` 中的 `VITE_PROXY` 即可（直连 `php artisan serve` 时改为 `http://admin.laravel13.elevue/api`，见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)），改后重启 `pnpm dev` 生效。
+
+确保后端服务已启动（Laragon 或 `php artisan serve`），然后访问 `http://localhost:8001`。

 ## 步骤五：验证前后端联调

@@ -151,7 +175,7 @@ target: 'http://admin.laravel13.elevue/api',
 4. 登录成功后进入控制台页面

 :::tip 代理原理
-浏览器 → `http://localhost:8001/api/login` → Vite 代理 → `http://localhost:8000/api/login` → 后端处理
+浏览器 → `http://localhost:8001/api/login` → Vite 代理（rewrite 去掉 `/api`、target 补回）→ `http://admin.laravel13.elevue/api/login` → 后端处理

 代理方式下前端无需关心跨域；若改为直连后端（`VITE_GLOB_API_URL` 配置完整地址），则依赖后端 CORS 配置（`.env` 中 `CORS_ALLOW_ORIGIN`）。
 :::
@@ -205,12 +229,12 @@ server: {
 检查后端服务是否启动，以及代理配置是否正确：

 ```bash
-# 确认后端在运行（直接请求后端验证码接口）
-curl http://localhost:8000/api/captcha
+# 确认后端在运行（直接请求后端验证码接口，默认虚拟主机）
+curl http://admin.laravel13.elevue/api/captcha
 # → {"code":0,...} 即后端正常
 ```

-再检查 `vite.config.ts` 中 `proxy.target` 是否指向后端实际地址（改完需重启 `pnpm dev`）。
+再检查 `.env.development` 中 `VITE_PROXY` 的目标地址是否指向后端实际地址（改完需重启 `pnpm dev`）。

 ### 4. 登录报 401