Vue Vben Admin

基于 pnpm workspaces + Turborepo 的 monorepo 项目，使用 Vue 3 + TypeScript + Vite 构建。提供多套 UI 库变体（Ant Design Vue、Element Plus、Naive UI），共享同一套基于 TailwindCSS + shadcn-vue 的核心框架。

项目结构

→ 详见 vben-dir

开发指南

主题	说明	参考
新增页面	创建视图组件、路由模块和国际化配置	vben-add-page
新增 API	添加带类型的 API 端点定义和可选的 Mock 路由	vben-add-api
新增 Store	使用 Composition API 创建 Pinia Store	vben-add-store
新增 Mock	在 Nitro 后端 Mock 服务中添加模拟路由	vben-add-mock
CRUD 模块	完整 CRUD：表格 + 搜索表单 + 新建/编辑弹窗 + API + 路由 + 国际化	vben-crud

组件参考

组件	说明	参考
Form 表单	适配多 UI 框架的表单组件，底层基于 vee-validate	vben-form
Modal 模态框	支持拖拽、全屏、自动高度、loading 的弹窗组件	vben-modal
Drawer 抽屉	支持自动高度、loading 的侧边抽屉组件	vben-drawer
Alert 轻量提示框	纯 JS 调用的 alert/confirm/prompt 提示框	vben-alert
Vxe Table 表格	基于 vxe-table 的列表组件，集成搜索表单	vben-vxe-table
ApiComponent 包装器	为组件提供自动获取远程数据的能力	vben-api-component
CountToAnimator 数字动画	数字滚动动画效果组件	vben-count-to-animator
EllipsisText 省略文本	超长文本省略、tooltip 提示、展开收起	vben-ellipsis-text

关键约定

路径别名

• #/* 映射到各应用的 ./src/*（在 package.json#imports 中定义）
• 应用内部导入始终使用 #/ 前缀：import { $t } from '#/locales'
• 共享包使用 @vben/ 前缀：import { preferences } from '@vben/preferences'

依赖管理

• 内部包："workspace:*"
• 第三方包："catalog:"（版本在 pnpm-workspace.yaml#catalog 中集中管理）

代码风格

• 所有 Vue SFC 使用 <script lang="ts" setup>
• 仅使用 Composition API，禁止 Options API
• 使用 TailwindCSS 工具类进行样式开发
• 所有用户可见文本使用 $t('key') 国际化
• 遵循 Conventional Commits 规范：feat、fix、chore、docs、refactor、perf、test

组件适配器模式

每个应用在 src/adapter/ 中桥接通用组件到具体 UI 库：

• component/index.ts — 通过 globalShareState.setComponents() 注册 UI 库组件映射
• form.ts — 通过 setupVbenForm() 配置表单系统（model 属性名等）
• vxe-table.ts — VXE Table 适配器

添加新的表单组件类型时：

1. 在 component/index.ts 中添加异步导入
2. 需要占位符的组件用 withDefaultPlaceholder() 包装
3. 添加到 ComponentType 联合类型
4. 在 initComponentAdapter() 的组件映射中注册

权限控制

三种访问模式，通过 preferences.app.accessMode 配置：

• frontend：按用户角色过滤静态路由
• backend：从 getAllMenusApi() 获取菜单并动态注册路由
• mixed：两者结合

路由 meta 选项：

• meta.ignoreAccess: true — 跳过权限检查
• meta.authority: ['admin'] — 限制特定角色（frontend 模式）
• meta.menuVisibleWithForbidden: true — 菜单中显示但跳转 403
• meta.affixTab: true — 固定标签页
• meta.hideInMenu: true — 从侧边菜单隐藏

UI 级别的权限控制：

<!-- 指令方式 -->
<button v-access:code="['permission-code']">操作</button>

<!-- 组件方式 -->
<AccessControl :codes="['permission-code']">
  <button>操作</button>
</AccessControl>

偏好设置系统

@vben/preferences 导出单例 preferences（响应式，自动持久化到 localStorage）。

各应用在 apps/<app>/src/preferences.ts 中覆盖默认配置：

import { defineOverridesPreferences } from '@vben/preferences';

export const overridesPreferences = defineOverridesPreferences({
  app: { name: 'My App' },
  theme: { mode: 'light' },
});

请求客户端拦截器

各应用的 src/api/request.ts 创建 RequestClient，包含以下拦截器：

1. 请求拦截：附加 Bearer Token + Accept-Language 请求头
2. defaultResponseInterceptor：解包 { code, data, message } 格式
3. authenticateResponseInterceptor：处理 401，刷新 token 或跳转登录
4. errorMessageResponseInterceptor：显示错误提示

国际化

• 框架级翻译：packages/locales/src/langs/
• 应用级翻译：apps/<app>/src/locales/langs/<locale>/*.json
• 模板中使用 $t('key')，脚本中从 #/locales 导入 $t('key')
• 第三方组件库的 locale 加载在 apps/<app>/src/locales/index.ts 中处理

Mock 后端

apps/backend-mock/ 是基于 Nitro 的服务端，使用 h3 路由 + faker.js 生成数据。

• API 路由位于 apps/backend-mock/api/
• 独立启动：pnpm -F @vben/backend-mock start
• Vite 开发服务器将 API 请求代理到此服务

核心包参考

包名	路径	用途
@vben/access	packages/effects/access	路由/菜单生成，权限指令
@vben/common-ui	packages/effects/common-ui	共享 UI（ApiComponent、IconPicker 等）
@vben/hooks	packages/effects/hooks	useAppConfig 等
@vben/layouts	packages/effects/layouts	BasicLayout、登录页、小部件
@vben/request	packages/effects/request	基于 Axios 的 RequestClient
@vben/preferences	packages/preferences	响应式偏好管理器
@vben/stores	packages/stores	全局 Pinia Store
@vben/locales	packages/locales	vue-i18n 工具
@vben/styles	packages/styles	全局 CSS / TailwindCSS 基础样式
@vben/utils	packages/utils	共享工具函数
@vben/types	packages/types	共享 TypeScript 类型
@vben/icons	packages/icons	Iconify 图标封装
@vben/constants	packages/constants	全局常量（LOGIN_PATH 等）

应用引导流程

main.ts → initApplication()：

1. initPreferences({ namespace, overrides }) — 加载/持久化偏好设置
2. bootstrap(namespace)：
   • initComponentAdapter() — 注册 UI 组件映射
   • initSetupVbenForm() — 配置表单系统
   • setupI18n(app) — 初始化国际化
   • initStores(app, { namespace }) — 初始化 Pinia Store
   • registerAccessDirective(app) — 注册 v-access 指令
   • initTippy(app) — 初始化 tooltip
   • app.use(router) — 安装路由（含导航守卫）
   • app.use(MotionPlugin) — 安装动画插件
   • 挂载到 #app

常用命令

pnpm dev              # 启动所有应用（开发模式）
pnpm build            # 构建所有应用
pnpm lint             # ESLint 检查
pnpm format           # Prettier 格式化
pnpm test:unit        # 运行单元测试（vitest）
pnpm check:circular   # 检查循环依赖
pnpm check:dep        # 检查未使用/缺失依赖
pnpm check:cspell     # 拼写检查
pnpm commit           # 交互式 Conventional Commit（czg）
pnpm typecheck        # vue-tsc 类型检查

# 启动特定应用
pnpm -F @vben/web-antd dev
pnpm -F @vben/backend-mock start