简介这是一份基于 Vue3 与 ElementPlus 的后台管理系统模板面向需要快速搭建中后台前端项目的开发者用来省去从零进行工程搭建、组件选型与目录规划的重复工作。压缩包共包含 62 个文件主要类型有 Vue 单文件组件、TypeScript 类型定义、JavaScript 交互脚本、JSON 项目配置和 Less 样式文件整体大小约 146KB结构紧凑便于直接解压学习或作为工程起点。模板中实际落地了 Vue3 的组合式 API、响应式引用、路由跳转、状态共享以及 ElementPlus 的布局、表格、表单、弹窗、主题定制等后台常用功能目录按视图、组件、状态、接口模拟、请求封装、环境配置等模块划分能帮助读者快速理清中后台项目从登录鉴权、权限控制到业务页面的整体实现思路。包内还加入开发与生产环境的变量配置、模拟接口数据并保留了 eslint 等工程化校验配置便于在此基础上继续扩展业务。目前已有 9663 人学习/下载整体目录边界相对清晰适合有一定 Vue 基础的开发者学习参考或按需抽取模块。1. Vue3 后台管理模板先拆骨架再动手后台管理系统大概是前端工程师写得最多的项目类型也是最容易被低估的登录、路由、权限、菜单、表格、弹窗每个模块单独看不难合在一起却总在联调阶段翻车。vue3 后台管理系统这个关键词之所以天天有人搜就是因为大家需要的不是又一套 UI 演示页而是一套把路由懒加载、登录态刷新、axios 拦截、mock 数据、多环境切换全部提前编排好的可运行骨架。这份基于 vue3elementPlus 的模板就是这种工程的完整样本适合刚接触 vue3 的开发者直接改写也适合有 vue2 经验的工程师对照 Composition API、Pinia 和 Element Plus 的真实搭配看看新版技术栈到底把哪些旧习惯改掉了。模板源码里藏着不少值得逐行读的细节从src/main.ts的入口注册方式到.env.development与.env.production的环境变量分工再到src/request下对 axios 实例的封装方式都值得拆开讲。2. Composition API 在后台模板里的三种落点模板内业务页面几乎全部采用script setup写法这背后不只是风格偏好而是 vue3 对响应式逻辑的一次重新组织setup 在组件实例创建前执行数据、计算属性和方法可以在函数维度内聚合不再被 data、computed、methods 三个抽屉强行切分。对后台管理系统来说这种组织方式的收益非常直观。2.1 页面级逻辑setup、ref 与 computed 的组合后台页面最典型的形态是筛选表单加表格加分页模板里这类页面的逻辑通常收敛成下面这样。用户管理、订单列表、配置管理逻辑骨架几乎一致。script setup langts import { ref, reactive, computed } from vue import { getUserList } from /api/user import type { UserItem } from /typed-request // 筛选条件和分页状态 const filter reactive({ keyword: , status: }) const page ref({ pageNum: 1, pageSize: 20 }) // 列表数据与总数 const list refUserItem[]([]) const total ref(0) // keyword 是否被填写用于控制重置按钮和搜索提示 const hasKeyword computed(() filter.keyword.trim().length 0) async function loadList() { const { rows, count } await getUserList({ ...filter, ...page.value }) list.value rows total.value count } loadList() /script这里的参数选择有讲究。filter用reactive包裹因为它内部字段固定筛选条件增删频率低list用ref因为表格数据需要整体替换。如果list也用reactive包裹整体赋值时很容易丢失响应式代理引用模板不会触发更新。computed在这里负责派生状态hasKeyword不需要单独维护任何地方修改filter.keyword后它都会自动变化。2.2 跨层共享provide / inject 替代深层 props 透传layout 布局组件需要把当前登录用户信息、菜单折叠状态、标签页缓存传递给深层子页面这些数据低频变化但传递链路深。vue2 时代的 props 逐层透传加事件冒泡在模板里被 provide 和 inject 直接替代中间层不再需要声明与自身无关的 props。// layout/index.vue import { provide, ref } from vue import { getUserInfo } from /api/user // 当前登录用户信息 const currentUser ref(await getUserInfo()) provide(currentUser, currentUser) // 任意深度的子组件 import { inject } from vue import type { Ref } from vue const currentUser injectRefUserInfo(currentUser)provide 和 inject 的适用边界需要说明它适合低频稳定数据比如用户信息只在登录态变化时更新一次。如果数据高频变化且被多个不相关模块消费仍然应该放进 Pinia。模板中两种方式并存正是对这种边界的体现。2.3 首屏体验Suspense 与 Teleport 的实际位置路由组件是异步加载的网络慢时会出现白屏。模板在App.vue外层用 Suspense 包住 RouterView异步组件还未就绪时先渲染 fallback用户体验比白屏好很多。!-- App.vue 路由出口 -- Suspense template #default RouterView / /template template #fallback div classpage-loading页面加载中.../div /template /SuspenseTeleport解决的是弹窗定位问题。后台 layout 的侧边栏和顶栏区域很容易出现 overflow 设置el-dialog 挂在组件内部时会被父级裁剪或产生 z-index 层叠异常。模板里把确认类弹窗统一传送到 body 下规避了这一类问题。Teleport tobody el-dialog v-modelvisible title批量导入 width480px el-upload drag :actionuploadUrl / /el-dialog /Teleport场景Vue2 常见写法模板中的 Vue3 写法请求列表数据methods 中调用data 中的 list 赋值script setup顶层异步函数跨层级传用户信息props 逐层透传 $emitprovide / inject弹窗挂载位置跟随组件渲染Teleport 到 body异步路由加载v-if loading 变量Suspense fallback 统一占位这套写法和 vue3 面试题里常问的响应式原理、组合式函数拆分逻辑正好对得上ref 负责基础值响应式reactive 负责对象内部字段依赖追踪computed 负责派生状态provide/inject 负责跨层级共享。3. Element Plus 按需集成与主题定制边界Element Plus 是 vue3 生态里后台管理系统最常用的组件库但很多时候项目停在能跑阶段没有处理包体体积、主题定制和多语言这几个问题。模板把这些点都做成了工程配置值得逐项对照。3.1 全局注册和按需自动导入怎么选简单项目在main.ts里执行app.use(ElementPlus)就能把组件库整包注册开发阶段方便但生产构建时 element-plus 全量组件和样式会让 chunk 体积膨胀得比较明显。模板采用按需自动导入通过 unplugin 系列插件在编译阶段解析模板中实际用到的组件只引入对应组件和样式。// vue.config.js const AutoImport require(unplugin-auto-import/webpack) const Components require(unplugin-vue-components/webpack) const { ElementPlusResolver } require(unplugin-vue-components/resolvers) module.exports { configureWebpack: { plugins: [ AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [ElementPlusResolver()] }) ] } }这套配置有两个容易踩的坑。第一启用自动导入后不要再全局引入element-plus/dist/index.css否则样式会重复打包。第二AutoImport只处理 API 级别的自动导入比如 ElMessage、ElMessageBox 这类函数式组件Components处理模板里的标签组件。ElementPlus 中文官网的安装章节对 vite 和 webpack 两种构建工具分别给过示例vue-cli 工程就是这个 webpack 版本。3.2 主题定制CSS 变量与 SCSS 重编译的分工Element Plus 提供两层定制手段。第一层是 CSS 变量覆盖在全局样式中重定义--el-color-primary这类变量简单直接适合只调整品牌色和圆角。第二层是 SCSS 变量重编译通过forward ... with在编译前修改色板适合需要完整定制色阶的场景。// src/style/element/index.scss forward element-plus/theme-chalk/src/common/var.scss with ( $colors: ( primary: ( base: #1677ff ) ) );/* 轻量定制CSS 变量方案 */ :root { --el-color-primary: #1677ff; --el-border-radius-base: 6px; }对比项CSS 变量覆盖SCSS forward 重编译生效阶段运行时编译时覆盖范围预设 CSS 变量更底层的 SCSS 变量动态主题切换支持运行时改变量即可不支持需重新构建项目适配成本低样式文件里直接覆盖中需要 sass 依赖和变量路径正确模板的主题文件放在src/style/element/下登录页、控制台图表、表格页共用这套变量方便统一换肤。3.3 组件组合与常见坑Element Plus 常用组件单独用都不复杂组合在一起才是后台开发的真实场景。组件组合业务场景必须关注的参数el-table el-pagination列表分页table 要设 row-key分页组件用 v-model:current-page 双向绑定el-form el-table表格行内编辑el-table 单元格放 el-input 时表单校验要和表格数据源对齐el-select remote远程搜索下拉设置 filterable remote :remote-method搜索回调返回新 optionsel-dialog el-form编辑弹窗dialog 打开时要重置表单配合 destroy-on-close 避免校验残留el-tabs el-table多标签数据切换每个 tab 的表格数据建议独立缓存避免切 tab 后页码丢失el-dialog有个高频问题第一次打开后关闭第二次打开时表单还是上次的输入。模板的常规处理是在open回调里执行formRef.resetFields()或者在 dialog 上配置destroy-on-close二选一即可两个都开会出现表单刚渲染就被重置的时序问题。4. 路由、Pinia 与 axios工程化骨架怎么接后台管理系统的工程质量基本由路由权限设计、状态管理选型、请求层封装这三块决定。模板在这三处提供的都是直接能跑的方案下面拆开看每块做了什么。4.1 配置化路由与懒加载约束模板的src/router目录把路由拆成静态路由和权限路由。静态路由包括登录页、404 页权限路由挂在 layout 下每个路由的meta字段声明标题、图标和可访问角色。所有页面组件使用动态 import 实现懒加载按路由分包。// router/index.ts import { createRouter, createWebHistory } from vue-router import type { RouteRecordRaw } from vue-router const routes: RouteRecordRaw[] [ { path: /login, name: Login, component: () import(/views/login/index.vue) }, { path: /, component: () import(/layout/index.vue), meta: { requiresAuth: true }, children: [ { path: dashboard, name: Dashboard, component: () import(/views/dashboard/index.vue), meta: { title: 控制台, icon: Odometer, roles: [admin] } } ] } ]meta.roles在这里是给路由守卫用的。登录成功后从后端拉取用户角色根据角色过滤出可访问的路由再用router.addRoute动态注册。模板在权限模块里预置了这个逻辑src/router下的权限文件配合 store 中的用户状态完成登录取角色、过滤路由、注册路由、生成菜单的完整链路。4.2 Pinia 替代 Vuex 4 的取舍模板的src/store目录使用 Pinia 而不是 Vuex 4。原因很直接Pinia 去掉了 mutations异步操作直接写在 actions 里TypeScript 推导比 Vuex 4 顺滑且 devtools 支持同样是官方维护。对后台模板来说用户状态、权限状态和标签页状态是三件套用 store 模块分别管理。// store/user.ts import { defineStore } from pinia export const useUserStore defineStore(user, { state: () ({ token: localStorage.getItem(token) || , roles: [] as string[] }), actions: { async login(payload: { username: string; password: string }) { const { token } await loginApi(payload) this.token token localStorage.setItem(token, token) }, async fetchUserInfo() { const userInfo await getUserInfoApi() this.roles userInfo.roles return userInfo } } })模板在 main.ts 里注册 Pinia 实例组件内通过useUserStore()直接消费。相比 Vuex 的mapState、mapGetters写法Pinia 的组合式调用在script setup里更干净也不需要 writable computed 去绕 getter 的限制。4.3 axios 实例与两层拦截器src/request下的封装是模板中另一个值得抄作业的部分。axios 实例统一配置 baseURL 和超时时间请求拦截器负责附加 token响应拦截器负责解包业务数据结构、处理错误码和 401 跳转。// request/index.ts import axios from axios import type { InternalAxiosRequestConfig } from axios const request axios.create({ baseURL: process.env.VUE_APP_BASE_API, timeout: 10000 }) // 请求拦截附加认证信息 request.interceptors.request.use( (config: InternalAxiosRequestConfig) { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }, (error) Promise.reject(error) ) // 响应拦截统一处理业务码 request.interceptors.response.use( (response) { const { code, data, message } response.data if (code 200) return data if (code 401) { localStorage.removeItem(token) window.location.href /login return Promise.reject(new Error(登录状态已过期)) } return Promise.reject(new Error(message || 请求失败)) }, (error) Promise.reject(error) )这里对响应拦截的职责做一层约定后端返回的格式统一为{ code, data, message }code 为 200 时直接解包返回 data业务组件里拿到的就是数据本体不需要再.then(res res.data)。401 时清除本地凭证并跳回登录页。如果响应拦截器里还要加重复请求取消逻辑可以用一个 Map 存储 pending 请求的 CancelToken新请求进来时先取消同 url 的旧请求。层级职责返回值请求拦截器附加 token、设置请求头、统一参数格式化处理后的 config响应拦截器成功分支解包业务数据、处理业务码、401 统一跳转data 本体或 reject响应拦截器失败分支超时、断网、5xx 的兜底提示Promise.reject4.4 devServer mock 与 data.json 联调模板的src/mock目录下放着 data.json通过 vue.config.js 的 devServer 中间件返回本地数据。这种方式不引入 mockjs请求层走的还是真实 axios 实例切换到后端联调时只需要关闭 mock 逻辑。// vue.config.js const mockData require(./src/mock/data.json) module.exports { devServer: { before(app) { app.get(/api/users, (req, res) { res.json({ code: 200, data: { rows: mockData.users, total: mockData.users.length } }) }) } } }这个中间件的注册时机在 webpack-dev-server 启动前只对本地开发环境生效。生产环境构建产物不包含这些 mock 接口部署时由 nginx 或其他网关把/api前缀代理到真实后端。模板在.env.production里配置了生产 API 地址开发和生产环境共享同一套 axios 实例只是 baseURL 不同。4.5 环境变量文件的生效规则vue-cli 本身内置 dotenv 解析模板中.env.development和.env.production分别对应vue-cli-service serve和vue-cli-service build时的环境加载。文件常见变量说明.env.developmentNODE_ENVdevelopment、VUE_APP_BASE_API/dev-api本地开发时请求前缀配合 devServer mock.env.productionNODE_ENVproduction、VUE_APP_BASE_API/api生产构建时使用由网关代理到后端需要注意的规则是只有以VUE_APP_开头的变量才会被注入到客户端代码的process.env中。NODE_ENV由 vue-cli 自己管理改它不生效。修改.env文件之后必须重启 dev server 或重新执行构建否则变更不会被加载这是新手最常见的改了没反应的原因。vue3 安装及环境配置相关的教程很多但真正决定开发体验的核心就是这一条规则。5. 权限指令与构建产物分包验证5.1 v-permission 按钮级指令路由级权限控制的是页面能不能进按钮级权限控制的是页面里的操作能不能点。模板在src/directive/permission.ts里实现了一个自定义指令基于当前用户角色判断按钮是否保留。// directive/permission.ts import type { Directive, DirectiveBinding } from vue import { useUserStore } from /store/user const checkPermission (el: HTMLElement, binding: DirectiveBinding) { const { value } binding const roles useUserStore().roles const hasPermission roles.some((role: string) value.includes(role)) if (!hasPermission el.parentNode) { el.parentNode.removeChild(el) } } export const permission: Directive { mounted: checkPermission }// main.ts import { permission } from ./directive/permission app.directive(permission, permission)使用方式是在按钮上声明可见角色el-button v-permission[admin] typeprimary新增用户/el-button指令和 v-if 的区别在于v-if 的表达式对页面所有经手人可见权限规则散落在模板里指令把校验逻辑收敛到一处角色列表调整时只改后端返回的 roles 数据即可。注意角色列表需要在路由守卫执行完用户信息拉取后再渲染页面否则应用首次挂载时 roles 还是空数组页面会被误删。5.2 构建产物与首屏分包检查模板在发布前的验证步骤建议按下面的顺序执行。# 以生产模式构建 npm run build -- --mode production # 本地静态验证构建产物 npx serve -s dist -l 8080打开浏览器开发者工具的网络面板检查两个关键点。第一dist/assets下应该按路由拆分成多个 js chunk每个页面一个独立文件登录页 chunk 里不应该出现控制台页面的代码。第二Element Plus 组件按需引入后ElMessage、ElMessageBox 这类函数组件会被单独拆分成公共 chunk重复出现在多个页面 chunk 里的组件字符串要尽量少。如果发现某个路由的 chunk 过大可以在vue.config.js里配置performance阈值或者把 echarts 这类大依赖从业务代码中拆出来单独分包。模板的vue.config.js里已经预留了splitChunks的配置位置实际项目按依赖体积填参数即可。这些检查项通过后剩下的工作就是让测试同学把权限用例完整过一遍了。本文还有配套的精品资源点击获取