2.3 前端服务启动

概述

前端为 Vue3 + TypeScript + Vite + Element Plus 工程（ui/ 目录），通过 pnpm 安装依赖后一条命令启动开发服务器，接口代理指向后端 :8000。

安装依赖

cd ui

# 推荐 pnpm（仓库脚本按 pnpm 编写）
pnpm install

# 国内镜像加速（可选）
pnpm config set registry https://registry.npmmirror.com

启动开发服务器

pnpm dev

启动后终端输出本地地址（默认 Vite 端口），浏览器访问即可看到登录页。

代理与接口地址

开发环境下 Vite 把 /api 代理到后端 http://127.0.0.1:8000（见 ui/vite.config.ts 的 proxy 配置）。前端 axios baseURL 为 /api，模块路径与后端 gmeta path 逐条对齐。

URL 约定

全部接口统一 /api 前缀，没有 /v1 版本段（api/v1 只是 Go 包名）。例如用户分页是 GET /api/user/page。公开路由（登录/验证码/令牌兑换/健康检查）同样不带版本段。

构建生产包

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 前端部署）。

常用脚本

命令	说明
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，通配权限 *:*:*）

演示模式

若 config.yaml 中 app.demo: true，所有写操作会被拦截并提示"演示环境，禁止操作!"。本地开发请保持 app.demo: false。

前端启动失败排查

• 依赖安装失败：切换 pnpm 镜像源；Node 版本低于 18 升级后再装
• 接口 404/跨域：确认后端已在 :8000 启动；开发代理仅在 pnpm dev 生效
• 登录页验证码不显示：后端未启动或 /api/captcha 被限流（认证入口默认 10 次/分钟/IP）
• 页面白屏：浏览器控制台看路由守卫报错；确认已登录或访问常量路由 /login