75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# 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`
|