签入版本

2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
@@ -1,13 +1,13 @@
-# 2.3 前端服务启动
+# 2.4 前端服务启动

 :::tip 概述
-本章指导您启动前端开发服务器，包括依赖安装、环境配置和 Vite 开发服务器启动。
+本章指导您启动前端开发服务器，包括依赖安装、环境配置和 Vite 开发服务器启动。前端为本仓库 `ui/` 目录内的 EleVue 管理后台（Vue3 + ElementPlus）。
 :::

 ## 步骤一：安装依赖

 ```bash
-# 进入前端项目目录
+# 进入前端项目目录（克隆/解压前端仓库至 ui/ 目录）
 cd ui

 # -----------------------------------------------------------------------------
@@ -21,7 +21,17 @@ npm install
 ```

 :::warning Node.js 版本
-前端项目要求 Node.js >= 18，推荐使用 22.x。可通过 `node -v` 检查版本。
+前端项目要求 Node.js >= 22（推荐 22.18.0）。可通过 `node -v` 检查版本，安装方式见 [2.1 开发环境准备](/zh/quickstart/environment.html)。
+:::
+
+:::tip 国内镜像
+安装速度较慢时配置镜像源：
+
+```bash
+pnpm config set registry https://registry.npmmirror.com
+# 或
+npm config set registry https://registry.npmmirror.com
+```
 :::

 ## 步骤二：配置环境变量
@@ -38,7 +48,7 @@ VITE_PORT = 8001
 VITE_PUBLIC_PATH = /

 # 代理配置（JSON 数组格式：[["前缀","目标地址"]]）
-VITE_PROXY = [["/api","http://admin.thinkphp6.elevue/api"]]
+VITE_PROXY = [["/api","http://localhost:8000/api"]]

 # API 接口基础路径（留空，由代理处理）
 VITE_GLOB_API_URL =
@@ -49,8 +59,8 @@ VITE_GLOB_API_URL_PREFIX = /api
 # 上传接口地址
 VITE_GLOB_UPLOAD_URL = /api/upload

-# 图片访问地址
-VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue
+# 图片访问地址（附件域名，对应后端 FILE_DOMAIN_URL）
+VITE_GLOB_IMG_URL = http://file.laravel13.elevue

 # 是否启用 Mock 数据（false = 使用真实后端 API）
 VITE_USE_MOCK = false
@@ -75,7 +85,7 @@ VITE_GLOB_API_URL_PREFIX = /api
 VITE_GLOB_UPLOAD_URL = /api/upload

 # 图片访问地址
-VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue
+VITE_GLOB_IMG_URL = https://file.example.com

 # 是否启用 gzip 压缩
 VITE_BUILD_COMPRESS = gzip
@@ -114,18 +124,24 @@ npm run dev
 ```typescript
 // ui/vite.config.ts
 server: {
-  port: 8001,                                       // 开发服务器端口（对应 VITE_PORT）
+  port: 8001,                                // 开发服务器端口（对应 VITE_PORT）
  proxy: {
    '/api': {
-      target: 'http://admin.thinkphp6.elevue/api',  // 后端服务地址（对应 VITE_PROXY）
-      changeOrigin: true,                            // 开启跨域（修改请求头的 Origin）
-      rewrite: (path) => path,                       // 保持路径不变（不做路径替换）
+      target: 'http://localhost:8000/api',   // 后端服务地址（对应 VITE_PROXY）
+      changeOrigin: true,                     // 开启跨域（修改请求头的 Origin）
+      rewrite: (path) => path,                // 保持路径不变（不做路径替换）
    },
  },
 }
 ```

-确保后端服务已启动（`php think run`），然后访问 `http://localhost:8001`。
+后端使用虚拟域名时（见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)），target 改为对应地址：
+
+```typescript
+target: 'http://admin.laravel13.elevue/api',
+```
+
+确保后端服务已启动（`php artisan serve`），然后访问 `http://localhost:8001`。

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

@@ -135,7 +151,9 @@ server: {
 4. 登录成功后进入控制台页面

 :::tip 代理原理
-浏览器 → `http://localhost:8001/api/login` → Vite 代理 → `http://admin.thinkphp6.elevue/api/login` → 后端处理
+浏览器 → `http://localhost:8001/api/login` → Vite 代理 → `http://localhost:8000/api/login` → 后端处理
+
+代理方式下前端无需关心跨域；若改为直连后端（`VITE_GLOB_API_URL` 配置完整地址），则依赖后端 CORS 配置（`.env` 中 `CORS_ALLOW_ORIGIN`）。
 :::

 ## 构建生产版本
@@ -153,7 +171,11 @@ pnpm build
 pnpm preview
 ```

-构建完成后，`ui/dist/` 目录包含可部署的静态文件。
+构建完成后，`ui/dist/` 目录包含可部署的静态文件，部署方式见 [11.5 前端部署](/zh/deploy/frontend.html)。
+
+:::tip
+后端仓库根目录的 `composer dev` / `composer setup` 也会执行 `npm run build`（构建后端 `resources/` 下的静态资源），与前端仓库的构建相互独立。
+:::

 ## 常见问题

@@ -183,9 +205,15 @@ server: {
 检查后端服务是否启动，以及代理配置是否正确：

 ```bash
-# 确认后端在运行（直接请求后端登录接口）
-# -X POST → POST 方法
-# -H      → 设置 Content-Type 为 JSON
-# -d      → 发送 JSON 请求体
-curl http://admin.thinkphp6.elevue/api/login -X POST -H "Content-Type: application/json" -d '{"username":"admin","password":"123456"}'
+# 确认后端在运行（直接请求后端验证码接口）
+curl http://localhost:8000/api/captcha
+# → {"code":0,...} 即后端正常
 ```
+
+再检查 `vite.config.ts` 中 `proxy.target` 是否指向后端实际地址（改完需重启 `pnpm dev`）。
+
+### 4. 登录报 401
+
+1. Token 过期 → 重新登录（access_token 默认 2 小时）
+2. 请求头格式错误 → 确保是 `Authorization: Bearer <token>`
+3. 后端 `JWT_SECRET` 变更 → 旧令牌全部失效，重新登录即可