管理端前端开发

管理端位于 admin-webui Git 子模块，基于 Vben Admin 5、Vue 3、TypeScript、Ant Design Vue、Vite 和 pnpm workspace。生产构建产物会复制到后端 static/admin/ 并由 go:embed 打进二进制。

工作区信息

项目	当前值
应用包	@vben/web-antd
包管理器	pnpm@10.10.0
Node 最低声明	>=20.10.0，构建推荐 Node 22
开发端口	5666
应用基路径	/admin/
路由模式	hash
生产 API	同源相对路径

常用命令

cd admin-webui
corepack enable
corepack install
pnpm install --frozen-lockfile
pnpm dev:antd
pnpm run check:type
pnpm run test:unit
pnpm run build:antd --filter='!./docs'

业务目录

目录	职责
apps/web-antd/src/api	请求函数和 TypeScript 类型
apps/web-antd/src/views	工作台、短链、系统设置、个人资料页面
apps/web-antd/src/router/routes/modules	路由模块
apps/web-antd/src/store	应用状态
apps/web-antd/src/locales	应用级语言资源
packages/*	Vben 共享基础包

请求客户端

所有业务请求通过 #/api/request 导出的 requestClient。拦截器会：

• 添加 Authorization: Bearer <token>；
• 从 Local Storage 的 dwz.workspace_id 添加 X-Workspace-Id；
• 添加当前界面语言；
• 从统一响应的 data 字段取值；
• 对非成功 code 展示错误信息。

新增 API 示例：

import { requestClient } from '#/api/request';

export interface Widget {
  id: number;
  name: string;
}

export function listWidgetsApi() {
  return requestClient.get<{ list: Widget[] }>('/api/v1/widgets');
}

组件只调用该函数，不直接创建新的 axios 实例。修改后端 DTO 时同步更新类型、表单和错误提示。

开发 API 地址

.env.development 默认：

VITE_PORT=5666
VITE_GLOB_API_URL=http://127.0.0.1:8080

个人端口覆盖写入不提交的 .env.local。生产 .env.production 的 API URL 为空，浏览器同源请求 /api/v1/*。

生产集成

pnpm run build:antd --filter='!./docs'
cd ..
mkdir -p static/admin
cp -R admin-webui/apps/web-antd/dist/. static/admin/
GOWORK=off CGO_ENABLED=0 go build -o dwz-server .

每次前端改动后都要重新复制并构建后端，否则二进制仍包含旧资源。不要提交包含本地 API 地址或测试凭据的 .env.local。

页面调试

• 页面空白：检查 /admin/assets/* 404、构建 base=/admin/ 和浏览器缓存。
• 请求 401：检查登录 Token、请求拦截器和后端地址。
• 请求 403：检查 dwz.workspace_id 对应成员角色。
• 新菜单不显示：核对路由模块、权限条件和中英文文案。
• 后端已更新但页面字段为空：核对 code/data 解包和 TypeScript 字段名。

相关章节：源码构建、API 约定。