简介采用Vue3、Vite与Element Plus构建的中后台管理系统模板适合需要快速搭建企业级后台的前端开发者。项目整合了路由管理、状态管理、权限控制、接口封装、国际化等核心模块借助Vite实现按需编译与热更新能显著降低从零搭建环境的成本。压缩包共331个文件以Vue组件、TypeScript、JavaScript、CSS文件为主另有PNG、SCSS、JSON等少量资源整体约6.39MB目录结构紧凑清晰。已有1364人学习下载。模板内含可直接运行的页面示例与通用布局便于在此基础上扩展具体业务同时可直观理解Vue3组合式API、动态路由与权限指令的实际落地方式无论用于项目开发还是技术学习都有不错的参考价值。1. 中后台管理系统模板为什么选 vue3 vite element-plus中后台和 C 端页面最大的不同在于它不追求炫酷的视觉表现而是把权限、菜单、路由、表格表单、多标签页这些重复劳动固定成一套可复用的骨架。vue3 vite element-plus 这套组合能成为当前中后台模板的主流选型核心原因是阅读成本低、生态向心力强。组合方案开始时是 Vue 官方推荐 Vite而 Element Plus 由饿了么团队对 Vue 3 的适配二者天然能捏合在一起模板的维护价值也就落在了工程化沉淀上路由权限、状态共享、接口封装、构建部署。适合的人群很清晰——需要快速搭建后台项目的团队、想从 Vue 2 生态迁移的工程师、以及希望拿到代码骨架而不是一页页抄样式的学习者。2. 用 vite 初始化 vue3 项目并接入 element-plus 组件库2.1 创建 vite vue3 项目的最小命令开发环境和 node 版本决定了初始化顺利度。Vite 5 要求 Node 18而新版本的 Vite 6 同样保持这个底线如果本机 Win7 或低版本 node 上跑不动需要先升级环境再做事。常见做法是直接用 npm 创建模板命令如下npm create vitelatest admin-template -- --template vue cd admin-template npm install npm run dev这个命令拉取的vue模板默认不带 TypeScript。若团队希望用 TS 写出可约束的类型应该改成--template vue-ts。二者差异不仅在.ts后缀文件还影响组件defineProps泛型推导、ref与reactive的类型收窄。不熟悉 TS 的项目用 JS 起步更快但中后台的权限模型和接口响应体建议用 TS 约束后期改造成本更低。create vite默认生成的目录带有src/和public/模板项目会在接下来的章节里继续加router/、store/、api/等目录这是中后台项目约定俗成的分层。2.2 element-plus 的按需自动导入配置element-plus 全量引入写起来省事但会拖慢首屏加载速度中后台页面一多体积问题就会被放大。推荐的做法是官方提供的unplugin-auto-import与unplugin-vue-components组合只打包被用到的组件和 API。配置位于vite.config.jsimport { defineConfig } from vite import vue from vitejs/plugin-vue import AutoImport from unplugin-auto-import/vite import Components from unplugin-vue-components/vite import { ElementPlusResolver } from unplugin-vue-components/resolvers export default defineConfig({ plugins: [ vue(), AutoImport({ resolvers: [ElementPlusResolver()], dts: src/auto-imports.d.ts }), Components({ resolvers: [ElementPlusResolver()], dts: src/components.d.ts }) ] })AutoImport负责ElMessage、ElMessageBox这类 API 形式的组件Components负责标签形式的el-button、el-table等。生成的d.ts文件用于 IDE 类型提示建议提交到 git。有一个容易忽略的点如果项目里用到了 element-plus 的中文语言包组件 DOM 不经过vite插件处理是可以的但日期组件 locale 需要手动设置import zhCn from element-plus/es/locale/lang/zh-cn app.use(ElementPlus, { locale: zhCn })如果已经走按需引入上面这行会失效需要在入口处用app.use(ElementPlus, { locale: zhCn })同时传入而不是分行调用两次use。组件内如果出现英文默认文本比如分页器的Total很大概率是 locale 配置没有生效不是 element-plus 的 bug。2.3 模板目录按中后台场景重新组织初始化的脚手架目录偏简单模板项目需要增加如下结构src/ api/ # 接口请求按模块拆分 assets/ components/ # 通用业务组件 layout/ # 后台整体布局侧边栏、顶栏、主内容 router/ # 路由定义与守卫 store/ # Pinia 模块 styles/ utils/ # 请求封装、工具函数 views/ # 页面组件layout是整个模板的视觉骨架包含Sidebar、Header、Tabs和Main。之所以独立成目录是为了让路由的 meta 信息比如标题、图标、是否缓存能直接驱动布局渲染避免每个页面自己写导航。中后台模板的价值也集中在这个骨架层把菜单生成、标签页缓存、全屏切换、用户下拉菜单都挂在layout上业务页面本身只关心内容区。组件级别的公共封装放进components/比如SvgIcon、Pagination等带业务含义的组件。这些组件与 element-plus 自带的全局组件互不冲突命名上注意不要以el-开头。此时项目已经具备模板化的目录雏形下一步把路由和权限串起来。3. 模板的骨架动态路由、权限控制与菜单 tab 联动3.1 路由表拆成 staticRoutes 和 dynamicRoutes中后台的权限过滤本质上是路由表过滤不是按钮级别的隐藏。把路由拆成两部分是常见做法staticRoutes放登录页、404、首页等不需要权限的基础路由dynamicRoutes放需要登录且按角色过滤的业务路由。示例结构// router/routes.js export const staticRoutes [ { path: /login, component: () import(/views/login/index.vue), meta: { title: 登录 } } ] export const dynamicRoutes [ { path: /system, component: () import(/layout/index.vue), meta: { title: 系统管理, icon: setting }, children: [ { path: user, component: () import(/views/system/user.vue), meta: { title: 用户管理, roles: [admin] } }, { path: role, component: () import(/views/system/role.vue), meta: { title: 角色管理, roles: [admin, editor] } } ] } ]roles字段放在 meta 里而非路由顶层是为了让父子路由各自独立判断。若角色只是挂在顶层路由上子页面的权限会混在一起过滤逻辑会变得难以追踪。组件使用() import()懒加载同时满足代码分割和首屏提速。需要注意的是children中的path不用加/这是相对路径写法加了绝对路径会让面包屑和高亮菜单生成逻辑出问题。3.2 路由守卫中动态注册路由并过滤角色权限有了路由表还要在前置守卫里做登录态判断和权限挂载。每次刷新浏览器后Pinia 里的用户信息和动态路由会丢失因此代码要兼容刷新重新拉取权限的场景。核心实现放在router/index.jsconst whiteList [/login] router.beforeEach(async (to, from, next) { const token localStorage.getItem(token) const userStore useUserStore() if (token) { if (to.path /login) { next({ path: / }) } else { const hasRoles userStore.roles userStore.roles.length 0 if (hasRoles) { next() } else { try { await userStore.fetchUserInfo() const routes filterAsyncRoutes(dynamicRoutes, userStore.roles) routes.forEach(route router.addRoute(route)) next({ ...to, replace: true }) } catch (err) { userStore.resetState() next(/login?redirect${to.path}) } } } } else { if (whiteList.includes(to.path)) { next() } else { next(/login?redirect${to.path}) } } })filterAsyncRoutes递归遍历动态路由表把meta.roles里不包含当前角色的路由过滤掉。next({ ...to, replace: true })是防止访问时路由已注册但菜单还没生成导致跳转失效。细节上addRoute添加的嵌套路由在与layout组合时要确保父级路由已在之前的注册中。404路由建议在动态路由注册完之后追加避免刷新时先命中 404 再被 add。整个判断顺序就是有无 token → 是否拉取用户信息 → 是否注册动态路由 → 放行。3.3 element-plus 菜单组件生成侧边栏并联动 tab动态路由注册后侧边栏的菜单可以顺势由userStore.menus驱动。常见做法是直接用过滤后的路由表渲染 el-menuel-menu :default-activeroute.path router background-color#001529 text-color#ffffff active-text-color#409eff MenuTree :menusmenuRoutes / /el-menuMenuTree递归组件内部对每一项判断是否有子路由有子路由用el-sub-menu没有则用el-menu-item。el-menu的router属性开启后点击菜单项会直接调router.push不再需要手动监听select事件。菜单与 tab 标签联动是中后台的高频需求。点击菜单打开一个 tabtab 激活态与当前路由一致关闭 tab 时回到最近的激活路由。这个状态放在 Pinia 的tabsStore里监听路由变化后 pushrouter.afterEach((to) { const tabsStore useTabsStore() if (!tabsStore.tabs.some(item item.path to.path)) { tabsStore.addTab({ path: to.path, title: to.meta.title, affix: to.meta.affix }) } })affix字段控制是否固定标签例如首页标签。关闭逻辑用el-tag的closable属性触发关闭后需要判断当前路由是否是被关闭的那个是则跳到下一个 tab。这个联动不涉及复杂算法但代码里最容易忽略的是菜单收起时默认激活高亮所以default-active要绑定route.path而不是菜单项 index。菜单的 index 由path拼出来遇到:id这类参数化路由时手动拼接会失效需要用route.matched最后一个 matched 段的 path。4. 状态管理与接口层Pinia 与 axios 请求封装4.1 Pinia 按模块划分中后台状态Vuex 在 Vue 3 里不再是唯一选择Pinia 以其更薄的 API 和天然的类型推导成为中后台模板的事实标准。划分模块时不要按页面来分而应按状态性质分典型如下// store/user.js import { defineStore } from pinia export const useUserStore defineStore(user, { state: () ({ token: localStorage.getItem(token) || , userInfo: {}, roles: [] }), getters: { isAdmin: state state.roles.includes(admin) }, actions: { async fetchUserInfo() { const res await getUserInfoApi() this.userInfo res.data this.roles res.data.roles }, logout() { this.token this.roles [] localStorage.removeItem(token) } } })Pinia 的 state 直接定义数据getters 依赖 state 且自动缓存actions 里this指向当前 store不需要 commit 和 mutation。模板里通常还会有tabs、app控制菜单折叠与全屏、permission三个模块但要注意别把接口请求放到 store 里store 只保存数据结果。用户信息里的头像、昵称等字段属于低变更数据可以从用户表接口一起返回不用单独维护一份 profile。4.2 axios 实例封装的核心参数与拦截器中后台的接口请求与前端页面解耦axios 封装承担了 baseURL、超时、headers、401 跳转、错误提示这些职责。以下是模板里常见的utils/request.js写法import axios from axios import { ElMessage } from element-plus import router from /router const service axios.create({ baseURL: import.meta.env.VITE_BASE_URL, timeout: 15000 }) service.interceptors.request.use( config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }, error Promise.reject(error) ) service.interceptors.response.use( response { const res response.data if (res.code ! 200) { ElMessage.error(res.message || 请求失败) return Promise.reject(new Error(res.message)) } return res }, error { if (error.response?.status 401) { localStorage.clear() router.push(/login) } else { ElMessage.error(error.message || 网络异常) } return Promise.reject(error) } )关键参数集中在三处baseURL绑定环境变量VITE_BASE_URL开发环境的代理与生产环境的网关地址分离不会出现写死测试地址部署到生产的情况timeout根据业务接口耗时来定上传文件的接口建议单独配置写统一的超时会在弱网场景下误杀response拦截器默认约定所有接口返回{ code, data, message }结构项目如果对接的是 Restful 风格接口则要改为直接返回response.data不强制统一 code 字段。401 统一清除本地状态并跳转登录比在每个页面catch里各自处理更可控。4.3 消除重复请求与取消机制中后台页面切换频繁列表页的搜索请求发出去后用户立刻跳转响应回来再 setState 可能报内存泄漏或渲染错误。模板里常见的处理是维护一套 pending map相同请求在未完成时直接取消const pending new Map() function getRequestKey(config) { const { method, url, params, data } config return [method, url, JSON.stringify(params), JSON.stringify(data)].join() } service.interceptors.request.use(config { const key getRequestKey(config) if (pending.has(key)) { const cancel pending.get(key) cancel() pending.delete(key) } config.cancelToken new axios.CancelToken(cancel { pending.set(key, cancel) }) return config }) service.interceptors.response.use( response { const key getRequestKey(response.config) pending.delete(key) return response }, error { if (axios.isCancel(error)) { return Promise.reject(new Error(重复请求已被取消)) } return Promise.reject(error) } )通过getRequestKey把 method、url、参数序列化作为唯一标识。搜索条件里若含时间戳这类动态字段则每次请求都会是新 key也就起不到取消作用需要手动剔除扰动字段。取消请求后会进入 error 分支通过axios.isCancel判断后静默处理不弹错误提示。另一个场景是路由切换后取消该页未完成的请求可以在router.afterEach里调用一个cancelAllRequest方法但要注意别误伤全局公共请求。5. 模板落地的工程化收尾与常见坑5.1 vite 多环境变量配置与 Nginx 部署 vue3 项目的注意点把环境相关的东西从代码里抽离是中后台模板成熟的标志。vite 采用import.meta.env在根目录创建.env.development和.env.production# .env.production VITE_BASE_URL/api VITE_OUTPUT_DIRdist在vite.config.js里读取export default defineConfig({ base: process.env.VITE_BASE_URL || /, build: { outDir: process.env.VITE_OUTPUT_DIR || dist, chunkSizeWarningLimit: 1024 } })base决定静态资源引用的前缀路径。部署到 Nginx 子路径时比如访问地址是https://example.com/admin/base必须设为/admin/否则资源加载 404。Windows 服务器上部署 vue3 项目和 Linux 没有本质差异把dist文件放到nginx/html/admin目录对应解如下location /admin/ { alias /usr/local/nginx/html/admin/; try_files $uri $uri/ /admin/index.html; }try_files指向index.html是为了前端路由 history 模式下刷新页面不 404。如果不是 history 而是 hash 路由则不需要这段配置。部署后如果接口请求失败优先看浏览器 Network 里请求路径是相对路径还是绝对地址多半是 nginx 的proxy_pass没有保留VITE_BASE_URL前缀。5.2 打包体积优化路由懒加载与 echarts 按需引入中后台引入 echarts 但只用了折线图和柱状图时全量import * as echarts会让打包体积多出几百 KB。echarts 5 版本后支持按需组合import * as echarts from echarts/core import { LineChart, BarChart } from echarts/charts import { GridComponent, TooltipComponent, LegendComponent } from echarts/components import { CanvasRenderer } from echarts/renderers echarts.use([LineChart, BarChart, GridComponent, TooltipComponent, LegendComponent, CanvasRenderer])按需注册后图表用echarts.init和setOption的写法不变但 title 等未注册组件会直接报错或静默不渲染。调试时遇到图表空白先检查echarts.use是否完整包含当前 option 里用到的组件。另外 element-plus 的组件加载已走自动导入比手动按需更省心不需要额外优化。5.3 中后台模板里容易踩的 3 个细节坑若依 vue3 ts 报错的一个典型来源是env.d.ts中缺少对import.meta.env的自定义类型声明。解决方案是在src下新增env.d.tsinterface ImportMetaEnv { readonly VITE_BASE_URL: string } interface ImportMeta { readonly env: ImportMetaEnv }不定义类型时未直接报错但编辑器里import.meta.env.VITE_BASE_URL无类型提示。第二个坑是 element-plus 菜单结合 tab 一起使用时el-menu的:default-active绑定参数化路由会失效因为route.path已经被替换成实际值但菜单项的 index 还是路由定义里的:id。处理办法是用route.matched最后一项的path作为 index。第三个坑是组件缓存keep-alive配合include时缓存的组件名必须是 SFC 里定义的name选项Vue 3.2 以后虽然没有强制但defineOptions里设置了name才能被keep-alive精确匹配否则缓存永远不命中。模板里建议所有列表页都显式声明组件名命名与路由 title 一致排查缓存问题会更顺手。本文还有配套的精品资源点击获取
