官方中文正文为项目官方提供的中文文档(原文转载),本站未作翻译、未改动文字,仅剔除图片与无关章节。
English | 中文
关于 v3
ElementAdmin v3 是一个基于 Vue 3 与 Element Plus 的后台管理模板。它不再追求大量演示页面和展示型组件封装,只保留后台应用长期稳定的基础能力:登录会话恢复、服务端动态路由、布局、TagsView、请求、表单、CRUD 状态、主题和国际化。具体业务页面、领域模型和交互流程由应用自行实现。
仓库采用 pnpm workspace。与应用无关的能力放在 packages,以后新增应用时可以复用,同时不会把 Admin 私有的路由、Store 或资源一起引入。
核心特性
- 纯服务端动态路由:业务路由由接口返回并在运行时注册,不再维护第二份前端角色过滤路由表。
- 四种常见布局:经典侧边栏、顶部导航、混合导航和双列侧边栏共用同一份路由树。
- 移动端适配:屏幕小于 768px 时自动使用移动端侧边栏。
- 明确的 Packages 边界:通用组件、CRUD/Form Hooks、请求客户端和主题变量相互独立。
- 图标完全离线:每个 App 只静态注册自己使用的 Iconify 图标,生产运行不依赖 CDN。
- 语言与主题即时切换:Vue I18n、Element Plus、HTML lang 和持久化状态保持同步。
- 克制的展示层:不提供 BaseButton,也不封装配置复杂的 Table、Search、Dialog、Detail。
- 独立文档应用:基于 VitePress,支持响应式布局、暗色模式和本地搜索。
技术栈
- Vue 3.5
- Vite 8
- TypeScript
- Element Plus 2
- Vue Router 5
- Pinia 4
- Vue I18n 11
- UnoCSS
- Axios
- ECharts 6
- VitePress 1
- Oxlint、Prettier、Stylelint
工作区结构
apps/
├─ admin/ 后台管理应用
└─ docs/ v3 文档站
packages/
├─ components/ 少量跨应用 UI 基础组件
├─ hooks/ 与 UI 无关的 useCrud、useForm
├─ request/ 与业务无关的 Axios 客户端
└─ styles/ 基础样式与主题变量
当前 packages 直接导出 workspace 源码,由各 Vite 应用编译,并不是已经预构建发布的 npm 包。
环境要求
- Node.js
^20.19.0 || ^22.13.0 || >=24.0.0 - pnpm
>=9.5.0,仓库固定使用pnpm@9.15.3 - Git
快速开始
git clone --branch master --single-branch https://github.com/kailong321200875/vue-element-plus-admin.git
cd vue-element-plus-admin
pnpm install
pnpm dev:admin
Admin 默认运行在 http://localhost:4000/。
用户名:admin
密码:admin
本地开发通过 Mock Server 提供内置接口;当 VITE_USE_MOCK=true 时,生产构建也会包含浏览器端 Mock 适配器,因此静态演示站无需后端即可完整使用。
常用命令
| 命令 | 说明 |
|---|---|
pnpm dev:admin |
启动 Admin 开发服务器 |
pnpm build:admin |
使用生产模式构建 Admin |
pnpm build:admin:dev |
使用开发环境变量构建 Admin |
pnpm build:admin:test |
使用测试环境变量构建 Admin |
pnpm preview:admin |
预览 Admin 生产构建 |
pnpm typecheck |
检查 Admin 与公共包的类型 |
pnpm dev:docs |
启动文档站 |
pnpm build:docs |
构建文档站 |
pnpm preview:docs |
预览文档构建 |
pnpm lint |
使用 Oxlint 检查整个工作区 |
pnpm format:check |
检查整个工作区的代码格式 |
pnpm style:check |
检查整个工作区的样式 |
包级测试:
pnpm --filter @vea/hooks test
pnpm --filter @vea/request test
文档
- 在线演示:element-plus-admin.cn
- v3 文档:docs.element-plus-admin.cn
在本地启动 v3 文档:
pnpm dev:docs
默认地址为 http://localhost:4002/。
element-plus-admin-doc.cn 对应旧版架构。新项目请以 v3 文档和当前分支代码为准。
动态路由约定
只有根 Layout、登录、重定向和错误页等运行外壳是静态路由。登录后,接口返回当前用户可访问的完整路由树。
component 值 |
含义 |
|---|---|
# |
后台 Layout |
## |
不挂载页面组件的路由分组 |
views/Dashboard/Analysis |
apps/admin/src/views 下的页面 |
路由图标必须由消费它的 App 注册,路由 name 必须全局唯一。
开发约定
- 业务 API 和模型放在
apps/admin,公共包不能反向导入应用代码。 - 只有形成稳定、与应用无关的契约后,才把代码下沉到
packages。 - Element Plus 组件显式导入,构建时按需补充组件样式。
- 使用 Oxlint,不再新增 ESLint 配置。
- 后端路由约定、路由多语言 key 和当前 App 的图标注册表需要保持一致。
提交前会通过 Husky 执行 vue-tsc、lint-staged 和 Commitlint。提交信息遵循 Conventional Commits:
feat: add user management
fix: resolve dynamic route refresh
docs: update deployment guide
refactor: simplify request client
如何贡献
欢迎提交 Issue 和 Pull Request。
- Fork 仓库。
- 创建分支:
git checkout -b feat/your-feature。 - 使用 Conventional Commit 信息提交修改。
- 推送分支,并向
master发起 Pull Request。
项目历史请查看更新日志。
浏览器支持
支持现代浏览器,不支持 Internet Explorer。
许可证
- 本文标题:vue-element-plus-admin - 一个基于 vue3
- 本文链接:https://www.cn121.com/webtheme/kailong321200875-vue-element-plus-admin.html
- 原项目:kailong321200875/vue-element-plus-admin 版权归原作者 kailong321200875 及贡献者所有
- 收录信息:本站于 2026-11-22 收录本项目,本页所列协议与仓库指标均为收录当时的状态;该日期之后原项目的版本更新与协议变更,本页不作同步。
- 开源协议:收录时本项目采用 MIT(查看 LICENSE 原文),本站转载其原始文档(未改动文字,仅剔除图片与无关章节);使用、修改、分发请以该仓库 LICENSE 原文为准。
- 站点出处:本文首发于 OneTwoOne,收录自 GitHub 开源项目 kailong321200875/vue-element-plus-admin。
- 内容说明:本页正文为项目官方提供的中文文档(原文转载),本站未作翻译、未改动文字,仅剔除了图片与赞助等无关章节、并把相对链接改为绝对地址;页首简介为机器翻译自仓库描述。
- 引用声明:商业转载、第三方聚合或 AI 检索训练引用时,请务必保留以上来源出处、本文永久链接,以及原项目的版权声明与许可信息。
- 下架通道:若原项目此后变更或收紧了许可协议、或作者/权利人认为本站的收录方式(译文、排版适配、简介翻译等)超出其授权范围,请通过 xyd3302001@163.com 发送下架通知,并附上项目地址与本页链接。本站核实后将第一时间删除本页内容,或改为不复制原文的目录性收录;署名更正等其他要求可一并提出。