# 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`