基于 Vue3 + TypeScript + Ant Design Vue 的现代化企业级后台管理系统，支持 COS 混合部署模式，提供完整的业务开发解决方案。
- 🎯 COS 混合部署: 支持腾讯云 COS 静态资源分离部署，提升访问速度
- 📊 动态表格/表单: 基于 JSON Schema 的动态表格和表单生成器
- 🧩 组件化架构: 严格的组件开发规范，支持业务组件和通用组件分离
- 🌐 国际化支持: 完整的 i18n 多语言解决方案
- 🎨 主题定制: 支持亮色/暗色主题切换和自定义主题
- 📱 响应式设计: 完美适配桌面端和移动端
- 🔐 权限管理: 基于角色的访问控制 (RBAC)
- ⚡ 性能优化: 路由懒加载、组件按需加载、虚拟滚动等
- 前端框架: Vue 3.5+ + TypeScript 5.x
- UI 组件库: Ant Design Vue 4.x
- 构建工具: Vite 5.x + Rollup
- 状态管理: Pinia + 持久化插件
- 路由管理: Vue Router 4.x
- 样式方案: UnoCSS + Less
- 代码规范: ESLint + Prettier + Husky
- 测试工具: Mock Service Worker (MSW)
- 部署方案: Docker + 腾讯云 COS
- Node.js >= 20.0.0
- Yarn >= 4.0.0
# 克隆项目
git clone https://github.com/buqiyuan/vue3-antdv-admin
# 进入项目目录
cd vue3-antdv-admin
# 安装依赖
yarn install
# 启动开发服务器
yarn dev
# 构建生产版本
yarn build
# 预览构建结果
yarn preview
# 部署到 COS (自动版本管理)
yarn deploy
# 指定版本类型部署
yarn deploy:major # 主版本号 +1
yarn deploy:minor # 次版本号 +1
yarn deploy:patch # 修订版本号 +1
# 清理指定版本
yarn deploy:clean
# 查看当前版本
yarn deploy:version
src/ ├── api/ # API 接口定义 │ ├── backend/ # 后端 API (自动生成) │ └── demo/ # 演示 API ├── assets/ # 静态资源 ├── components/ # 组件库 │ ├── basic/ # 基础组件 │ ├── business/ # 业务组件 │ └── core/ # 核心组件 (动态表格/表单) ├── hooks/ # 组合式函数 ├── layout/ # 布局组件 ├── locales/ # 国际化配置 ├── router/ # 路由配置 ├── store/ # 状态管理 ├── styles/ # 全局样式 ├── utils/ # 工具函数 └── views/ # 页面组件 ├── dashboard/ # 仪表盘 ├── system/ # 系统管理 └── ...
views/ └── 业务模块名/ └── 页面名称/ ├── index.vue # 页面主文件 ├── components/ # 页面专用组件 │ ├── EditModal.vue │ └── DetailDrawer.vue └── hooks/ # 页面专用逻辑 └── useTableData.ts
<template> <div class="page-container"> <div class="page-header"> <h1>{{ title }}</h1> </div> <div class="page-content"> <!-- 页面内容 --> </div> </div> </template> <script lang="ts"> import { defineComponent, reactive, toRefs, onMounted } from 'vue' export default defineComponent({ name: 'PageName', setup() { // 响应式数据 const state = reactive({ title: '页面标题', loading: false, dataSource: [], }) // 业务方法 const methods = { /** * 初始化页面数据 */ async initData() { state.loading = true try { // 数据加载逻辑 } finally { state.loading = false } }, /** * 处理用户操作 */ handleAction() { // 操作逻辑 }, } // 生命周期 onMounted(() => { methods.initData() }) return { ...toRefs(state), ...methods, } }, }) </script> <style lang="less" scoped> .page-container { @apply p-4; } .page-header { @apply mb-4 pb-4 border-b border-gray-200; } .page-content { @apply bg-white rounded-lg p-4; } </style>
- 基础组件 (
components/basic/): 通用 UI 组件，无业务逻辑 - 业务组件 (
components/business/): 包含特定业务逻辑的组件 - 页面组件 (
views/*/components/): 页面专用组件
- 单一职责: 每个组件只负责一个功能
- 数据操作内化: API 调用和数据处理在组件内部完成
- UI 反馈内化: 消息提示、确认框等与业务操作一起处理
- 事件通信简化: 减少复杂数据传递，优先使用简单通知机制
components/basic/组件名/ ├── index.vue # 组件主文件 ├── types.ts # 类型定义 ├── hooks/ # 组件专用逻辑 │ └── useComponentLogic.ts └── __tests__/ # 单元测试 └── index.test.ts
// api/demo/user.ts
import { request } from '@/utils/request'
export interface UserInfo {
id: number
name: string
email: string
}
export interface UserListParams {
page: number
pageSize: number
keyword?: string
}
/**
* 获取用户列表
*/
export function getUserList(params: UserListParams) {
return request<UserInfo[]>({
url: '/api/users',
method: 'GET',
params,
})
}
/**
* 创建用户
*/
export function createUser(data: Omit<UserInfo, 'id'>) {
return request<UserInfo>({
url: '/api/users',
method: 'POST',
data,
})
}
// 在组件中使用
import { message } from 'ant-design-vue'
import { createUser, getUserList } from '@/api/demo/user'
const methods = {
/**
* 加载用户数据
*/
async loadUsers() {
try {
state.loading = true
const response = await getUserList({
page: state.pagination.current,
pageSize: state.pagination.pageSize,
keyword: state.searchKeyword,
})
state.dataSource = response.data
state.pagination.total = response.total
}
catch (error) {
message.error('加载用户数据失败')
console.error('Load users error:', error)
}
finally {
state.loading = false
}
},
/**
* 创建用户
*/
async handleCreateUser(userData: Omit<UserInfo, 'id'>) {
try {
await createUser(userData)
message.success('用户创建成功')
// 刷新列表
await methods.loadUsers()
}
catch (error) {
message.error('用户创建失败')
throw error // 让调用方处理错误
}
},
}
// store/modules/user.ts
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', {
state: () => ({
userInfo: null as UserInfo | null,
permissions: [] as string[],
token: '',
}),
getters: {
isLoggedIn: state => !!state.token,
hasPermission: state => (permission: string) =>
state.permissions.includes(permission),
},
actions: {
/**
* 用户登录
*/
async login(credentials: LoginParams) {
const response = await loginApi(credentials)
this.token = response.token
this.userInfo = response.userInfo
this.permissions = response.permissions
return response
},
/**
* 用户登出
*/
logout() {
this.token = ''
this.userInfo = null
this.permissions = []
},
},
persist: {
key: 'user-store',
storage: localStorage,
paths: ['token', 'userInfo'],
},
})
- 命名规范: 使用 camelCase 命名变量和函数，PascalCase 命名组件和类
- 文件命名: 组件文件使用 PascalCase，其他文件使用 kebab-case
- 注释规范: 所有函数必须添加 JSDoc 注释说明功能、参数和返回值
- 类型定义: 严格使用 TypeScript，避免使用
any类型
- 组件懒加载: 路由组件使用动态导入
- 列表虚拟化: 大数据量列表使用虚拟滚动
- 图片优化: 使用 WebP 格式，添加懒加载
- 缓存策略: 合理使用 keep-alive 缓存页面
- 优先使用 UnoCSS: 原子化 CSS 类，提高开发效率
- 组件样式隔离: 使用
scoped避免样式污染 - 响应式设计: 使用 UnoCSS 响应式前缀适配不同屏幕
- 主题变量: 使用 CSS 变量支持主题切换
- 统一错误处理: 在 request 拦截器中处理通用错误
- 用户友好提示: 使用 message 组件显示操作结果
- 错误边界: 使用 ErrorBoundary 组件捕获组件错误
- 日志记录: 重要操作添加日志记录
- XSS 防护: 用户输入内容进行转义处理
- CSRF 防护: API 请求携带 CSRF Token
- 权限校验: 前端路由和后端接口都要进行权限校验
- 敏感信息: 不在前端存储敏感信息
- Vue Language Features (Volar)
- TypeScript Vue Plugin (Volar)
- ESLint
- Prettier
- UnoCSS
- Auto Rename Tag
- Bracket Pair Colorizer
# 代码检查
yarn lint
# 代码格式化
yarn lint:fix
# 类型检查
yarn type-check
# 清理缓存
yarn clean:cache
# 生成 API 类型
yarn openapi
遵循 Conventional Commits 规范：
feat: 新功能fix: 修复问题docs: 文档更新style: 代码格式调整refactor: 代码重构perf: 性能优化test: 测试相关chore: 构建工具或依赖更新
- Fork 项目到个人仓库
- 创建功能分支:
git checkout -b feature/new-feature - 提交代码:
git commit -m 'feat: add new feature' - 推送分支:
git push origin feature/new-feature - 创建 Pull Request
默认账号: admin / a123456
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
