签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,74 @@
+# 2.3 前端服务启动
+
+:::tip 概述
+前端为 Vue3 + TypeScript + Vite + Element Plus 工程（`ui/` 目录），通过 pnpm 安装依赖后一条命令启动开发服务器，接口代理指向后端 `:8000`。
+:::
+
+## 安装依赖
+
+```sh
+cd ui
+
+# 推荐 pnpm（仓库脚本按 pnpm 编写）
+pnpm install
+
+# 国内镜像加速（可选）
+pnpm config set registry https://registry.npmmirror.com
+```
+
+## 启动开发服务器
+
+```sh
+pnpm dev
+```
+
+启动后终端输出本地地址（默认 Vite 端口），浏览器访问即可看到登录页。
+
+## 代理与接口地址
+
+开发环境下 Vite 把 `/api` 代理到后端 `http://127.0.0.1:8000`（见 `ui/vite.config.ts` 的 proxy 配置）。前端 axios baseURL 为 `/api`，模块路径与后端 gmeta path 逐条对齐。
+
+::: tip URL 约定
+全部接口统一 `/api` 前缀，**没有 `/v1` 版本段**（`api/v1` 只是 Go 包名）。例如用户分页是 `GET /api/user/page`。公开路由（登录/验证码/令牌兑换/健康检查）同样不带版本段。
+:::
+
+## 构建生产包
+
+```sh
+pnpm build          # production 模式构建
+pnpm build:prod     # 显式 production
+pnpm build:uat      # uat 环境
+pnpm build:test     # test 环境
+pnpm build:dev      # dev 环境
+```
+
+构建产物经 `build/script/postBuild.ts` 后处理，输出 `dist/`，交给 Nginx 等静态服务器托管（部署见 [11.5 前端部署](../deploy/frontend)）。
+
+## 常用脚本
+
+| 命令 | 说明 |
+|------|------|
+| `pnpm dev` | 启动开发服务器 |
+| `pnpm build` | 生产构建 |
+| `pnpm type:check` | vue-tsc 类型检查 |
+| `pnpm lint:eslint` | ESLint 修复 |
+| `pnpm lint:prettier` | Prettier 格式化 |
+| `pnpm lint:stylelint` | Stylelint 样式检查 |
+| `pnpm preview` | 构建并本地预览 |
+
+## 本地测试账号
+
+| 账号 | 密码 | 角色 |
+|------|------|------|
+| admin | 123456 | 超管（ROLE_SUPER_ADMIN，通配权限 `*:*:*`） |
+
+::: warning 演示模式
+若 `config.yaml` 中 `app.demo: true`，所有写操作会被拦截并提示"演示环境，禁止操作!"。本地开发请保持 `app.demo: false`。
+:::
+
+## 前端启动失败排查
+
+ **依赖安装失败**：切换 pnpm 镜像源；Node 版本低于 18 升级后再装
+ **接口 404/跨域**：确认后端已在 `:8000` 启动；开发代理仅在 `pnpm dev` 生效
+ **登录页验证码不显示**：后端未启动或 `/api/captcha` 被限流（认证入口默认 10 次/分钟/IP）
+ **页面白屏**：浏览器控制台看路由守卫报错；确认已登录或访问常量路由 `/login`