vue-pure-admin 版本演进路线图：从 2.0.0 到 7.0.0 的架构升级、功能迭代与关键实现解析

导读

vue-pure-admin 是基于 Vue 3、Vite、Element-Plus 与 TypeScript 打造的后台管理系统（兼容移动端），本文以仓库根目录 CHANGELOG.zh_CN.md 为主线，系统梳理从 2.0.0（2021-04）到 7.0.0（2026-04）共五个大版本周期、二十余次发布的技术演进脉络。读者将了解到：全面 ESM 化的推进路径、构建链从 Rollup/esbuild 向 Rolldown/Oxc 的迁移、RBAC 权限体系的成型、无感刷新 Token 的实现原理、以及路由、标签页、国际化、主题等核心模块的迭代方向。文章在还原 CHANGELOG 全部要点的同时，结合当前仓库源码与配置文件给出可验证的实现依据，可作为升级决策、二次开发与代码阅读的参考地图。

一、版本全景与演进主线

vue-pure-admin 的发布历史可分为五个阶段，每个阶段解决的核心问题各不相同：

阶段	版本区间	时间跨度	核心主题
起步期	2.0.0 ~ 2.9.0	2021-04 ~ 2022-02	多导航模式、暗黑主题、国际化与本地存储体系奠基
集成期	3.0 ~ 3.9.7	2022-02 ~ 2022-12	主题重构、图标按需引入、首屏性能大优化、纯函数工具集外置
能力期	4.0.0 ~ 4.5.0	2023-05 ~ 2023-06	函数式弹框、标签页缓存与 keepAlive 体系、自定义指令补全
平台期	5.0.0 ~ 5.9.0	2024-02 ~ 2024-12	全面 ESM 化、RBAC 权限升级、组件示例库大规模扩充
现代期	6.0.0 ~ 7.0.0	2025-04 ~ 2026-04	AI 示例、tailwindcss v4、构建链全面现代化（Rolldown/Oxc）

当前仓库 package.json 声明版本为 7.0.0，运行环境要求 node >= 22.22.1、pnpm >= 11，并规定使用 only-allow 强制包管理器为 pnpm。这正好对应 CHANGELOG 中 5.6.0 起对 pnpm 版本要求逐步收紧、5.0.0 对 node 版本要求逐步上调、7.0.0 升级 TypeScript v6 的演进结果。

二、7.0.0：工程链全面现代化

7.0.0（2026-04-07）是当前最新版本，改动集中在构建工具链、工程规范与基础设施层，是理解现代版 vue-pure-admin 的关键切入点。

1. 构建链迁移：vite8 + Rolldown + Oxc

CHANGELOG 明确记录：升级 vite 至 v8 版本，并从 Rollup 与 esbuild 转向 Rolldown 与 Oxc。这一决策在 vite.config.ts 中得到直接印证——构建配置已使用 rolldownOptions 替代传统的 rollupOptions，并在此处配置静态资源分类打包规则：

rolldownOptions: {
  input: { index: pathResolve("./index.html", import.meta.url) },
  output: {
    chunkFileNames: "static/js/[name]-[hash].js",
    entryFileNames: "static/js/[name]-[hash].js",
    assetFileNames: "static/[ext]/[name]-[hash].[ext]"
  }
}

配套的还有 server.warmup 预热配置（预转换缓存入口文件与 views/components 目录，降低启动期间的初始加载时长并防止转换瀑布），以及 build.target: "es2015"（打包产物默认面向原生支持 ES2015 的浏览器，这条规则自 5.0.0 起沿用至今）。

2. 导航守卫：return 取代即将弃用的 next()

vue-router 新版本中 next() 即将被弃用，7.0.0 在导航守卫中改用 return 语句返回路由决策。在 src/router/index.ts 的 router.beforeEach 中可以清晰看到整套返回值用法：无权限时 return { path: "/error/403" }、隐藏首页时 return { path: "/error/404" }、外链时 return false、已登录访问白名单时 return toCorrectRoute()（保持当前页面）、未登录时 return { path: "/login" }。同时 router.afterEach 配合 loadedPaths 记录已加载页面路径，用于控制 NProgress 进度条只在页面重进时出现——这正是 6.2.0 中"页面重进或接口请求时不再显示进度条"优化的落点。

3. 全局配置字段更名：ShowModel → TagsStyle

public/platform-config.json 中全局配置项 TagsStyle 即由 7.0.0 从 ShowModel 更名而来，用于控制标签页（页签）风格，当前值为 "chrome"（谷歌风格，自 5.7.0 引入）。该文件通过 src/config/index.ts 的 getPlatformConfig 在应用启动时以 axios 请求 platform-config.json 动态加载并注入全局配置，缺失时会抛出"请在public文件夹下添加platform-config.json配置文件"的明确提示。配置面板还包括 ResponsiveStorageNameSpace（本地响应式存储命名空间，默认 "responsive-"）、CachingAsyncRoutes（动态路由是否缓存本地，默认 false）、TooltipEffect、MenuArrowIconNoTransition、Watermark 等多项全局开关。

4. 类型系统与代码规范升级

• typescript 升级至 v6，eslint 升级至 v10，stylelint 升级至 v17；
• 引入 eslint-plugin-better-tailwindcss 优化 tailwindcss 类名排序与提示；
• 重构全局类型声明，新增 PascalCase 转 kebab-case 的类型映射，使全局注册组件在 TSX 中支持 kebab-case 写法并获得完整类型提示（对应 types/global-components.d.ts 一类声明文件）；
• 使用 vueuse 的 useInfiniteScroll 替换 v3-infinite-loading 库（package.json 的 dependencies 中已无 v3-infinite-loading，@vueuse/core 为 ^14.4.0）；
• CDN 模式移除 pinia 与 vue-demi（新版本 pinia 已不依赖 vue-demi，但其生成的 iife 文件仍存在问题，修复后再回归 CDN 模式）；
• 精简 .husky 文件、优化 prettier 配置、规范 directives.d.ts 与 shims-vue.d.ts 类型声明。

5. 功能与体验更新

• layout 右上角操作按钮添加动效；
• RePureTableBar 与 ReVxeTableBar 组件实现全量文本国际化，并新增固定列功能（对应 src/components/RePureTableBar 与 src/components/ReVxeTableBar）；
• 刷新 token 接口请求失败后跳转登录页重新登录；
• layout 消息下拉框新增"查看更多"与"标为已读"功能（对应 src/layout/components/lay-notice）；
• 系统配置面板新增全屏水印功能（对应 src/views/able/watermark.vue）；
• 修复文件上传演示接口、this.$storage 类型、ReDialog/ReDrawer 切换路由时弹层未关闭、菜单搜索重复显示等问题；
• axios 版本锁定修复（CHANGELOG 记录为 1.14.0，当前仓库 package.json 中为 1.18.1，属后续迭代更新）。

三、6.x：体验精细化与组件 API 适配

6.x 系列（6.0.0 ~ 6.3.0）聚焦主题命名规范化、Element-Plus API 适配与错误页体验。

1. 主题与导航命名规范化（6.3.0）

系统配置中"整体风格"更名为"主题模式"、"导航模式"更名为"菜单布局"，public/platform-config.json 中的 Theme（当前 "light"）、DarkMode、Grey、Weak、Layout（当前 "vertical"）等字段即对应关系。同时迁移 typescript-eslint 已弃用的 tseslint.config 配置方式，并新增颜色选择器面板组件（对应 src/components/color-picker-panel.vue）。

2. Element-Plus 新版本 API 适配（6.3.0）

ReDialog、ReDrawer、message 工具函数均适配 el-dialog、el-drawer、ElMessage 最新版 API 变更并补充相关示例（示例位于 src/views/components/dialog、src/views/components/drawer，message 实现位于 src/utils/message.ts），并导入 element-plus 最新版本的新组件、优化谷歌页签风格布局。

3. 全屏错误页（6.2.0）

新增全屏 403、404、500 页面（src/views/error/403.vue、src/views/error/404.vue、src/views/error/500.vue），全屏错误页面清晰且安全，捕获所有未匹配路由并跳转全屏 404 的时机得到优化。页面使用 v-motion 动效与 @/assets/status/ 下的 SVG 插画（404.svg 等）。同时修复了 keepAlive 缓存、多标签页同时激活、params 传参标签页右键菜单等一系列缓存边界问题。

4. 性能与工程细节（6.1.0 / 6.2.0）

• 升级至 vite7 并做相关兼容处理；
• 优化 NProgress 进度条显示时机；
• 显式配置 Tailwind CSS 入口文件路径，优化 IntelliSense 插件上下文识别（对应 src/style/tailwind.css）；
• 修复 ReSegmented 深浅主题切换闪烁、resetRouter 未清空全部路由数据、关闭左侧标签页异常等问题；
• 升级 @pureadmin/table 兼容最新版 element-plus 的 el-table 全部 API。

四、5.x：全面 ESM 化与 RBAC 权限体系成型

5.0.0（2024-02-26）是影响最深远的架构版本，官方定位为"全面 ESM 版本"。

1. 全面 ESM 化改造

• 升级 vite 至 v5，规定 node > 18.18.0、pnpm >= 8.6.10（此后逐步上调至当前 package.json 的 node >= 22.22.1、pnpm >= 11）；
• 使用 vite-plugin-fake-server 替换 vite-plugin-mock，使用 @faker-js/faker 替换 mockjs（当前 package.json 与 mock 目录即是其落地，mock/refreshToken.ts 使用 defineFakeRoute 定义模拟接口）；
• tailwind.config.js、.prettierrc.js、postcss.config.js、commitlint.config.js 全部改为 .ts 或遵循 ESM 语法的 eslint.config.js（替换 .eslintrc.js）；
• stylelint 升级至 16 版本并遵循 ESM 语法（当前为 v17）；
• VITE_PUBLIC_PATH 默认还原为 /，对 VITE_ROUTER_HISTORY 为 h5 模式更友好（该历史模式逻辑在 src/router/utils.ts 的 getHistoryMode 中实现）。

2. RBAC 权限体系与无感刷新 Token

5.0.0 带来了完整的系统管理模块（菜单管理、用户管理）与免登录方案；权限模型在更早的 3.6.0 已重构为 RBAC（用户 → 角色 → 权限）。当前权限体系可从以下源码交叉印证：

• 角色与按钮权限存储在 src/utils/auth.ts 的 DataInfo 中，setToken 将 accessToken/expires/refreshToken 三条信息放入 authorized-token Cookie，将头像、用户名、昵称、角色、权限及 refreshToken、expires 共七条信息放入 user-info 的 localStorage，并通过 multiple-tabs Cookie 支持多标签页免登录（浏览器完全关闭后自动销毁）；
• 页面级权限判断在 src/router/index.ts 导航守卫中执行：to.meta?.roles && !isOneOfArray(to.meta?.roles, userInfo?.roles) 时返回 /error/403；
• 按钮级权限提供组件（RePerms）、函数（hasPerms）与指令（v-perms）三种操作模式，5.8.0 又新增根据登录接口 permissions 字段判断的第二种按钮权限指令，详见 src/components/RePerms、src/directives/perms 与 src/utils/auth.ts 的 hasPerms；
• token 过期后的无感刷新在 src/utils/http/index.ts 中实现：请求拦截器先判断白名单（/refresh-token、/login），再检查 expires 是否过期；过期且未在刷新中时通过 PureHttp.isRefreshing 防止重复刷新，调用 src/store/modules/user.ts 的 handRefreshToken 获取新 token，并将暂存的请求（PureHttp.requests）逐一重放；刷新失败则 logOut() 并提示登录过期——这正是 7.0.0"刷新 token 接口请求失败后跳转到登录页面"的延续。

对应的模拟接口见 mock/refreshToken.ts，其返回的 expires: "2030/10/30 23:59:59" 采用日期字符串格式以方便调试，注释明确说明后端返回时间戳时的改造位置。

3. 路由体系：自动导入与标签页/缓存完善

5.x 起静态路由平台自动导入，无需手动引入。src/router/index.ts 使用 import.meta.glob 匹配 ./modules/**/*.ts（排除 remaining.ts），再经过 ascending（排序）、buildHierarchyTree（建树）、formatFlatteningRoutes（拍平）、formatTwoStageRoutes（三级以上拍成二级）四步加工得到 constantRoutes。4.0.0 引入的 showLink: false 不添加到标签页、fixedTag 固定标签页不可关闭、activePath 指定激活菜单等路由 meta 配置均持续演进。

5.0.0 还包含：内嵌 iframe 支持 keepAlive、免登录天数选择、音频可视化（src/views/able/wavesurfer）、WebAssembly 视频帧截取（src/views/able/video-frame）、localforage 二次封装支持过期时间（src/utils/localforage）、ReAnimateSelector、ReText 省略组件、vite-plugin-router-warn 根治动态路由警告等大量新增。

4. 中后期：图标重构与主题升级

6.0.0 使用 @iconify/json 替换不再维护的 @iconify-icons/* 依赖（支持 Tree-shaking），升级 tailwindcss 至 v4（专属 vite 插件，对应 package.json 的 @tailwindcss/vite），并新增 AI 聊天组件（src/views/chatai）、代码编辑器（src/views/codemirror）、Markdown（src/views/markdown）、滑块等示例。5.9.0 将 vite 升级至 v6、sass 升级至最新版，重构主题写法并弃用 @pureadmin/theme；用 code-inspector-plugin 替换 vite-plugin-vue-inspector。

五、4.x：函数式弹框、标签页缓存与指令体系

4.x 系列（2023-05 ~ 2023-06）虽发布时间集中，却奠定了现代版框架的多个核心机制。

• 函数式弹框组件：4.0.0 新增 ReDialog，此后持续增强——updateDialog 更新属性、全屏按钮、beforeCancel/beforeSure 暂停关闭、Popconfirm 气泡确认、确定按钮 loading 动画（5.8.0 的 closeLoading）、子组件 primitive 类型 prop 示例，实现位于 src/components/ReDialog；
• 页面切换性能：4.4.0 记录页面切换逻辑（不考虑网络）速度比之前快约 3-4 倍，并持续优化 keepAlive 缓存边界——如修复首次加载未缓存、点击标签页重新加载时缓存未清、路由 query/params 传参开启缓存后关闭标签页缓存失效等一系列问题；
• 自定义指令体系：4.4.0 添加防抖、节流与文本复制指令并规范错误提示；4.5.0 添加支持自定义时长持续回调的长按指令；5.2.0 添加 v-ripple 水波纹指令。当前统一汇总于 src/directives/index.ts，包含 auth、copy、longpress、optimize、perms、ripple 六类；
• 路由 meta 扩展：activePath（query/params 传参路由配置 showLink: false 后仍可指定激活菜单）、fixedTag（固定标签不可关闭，5.4.0）等；
• 其他：5.4.0 引入 MaxTagsLevel 全局配置控制标签页最大数、框架核心代码国际化全量覆盖（仅需处理业务代码）；4.3.0 添加 Docker 支持（对应仓库根目录 Dockerfile）与项目版本实时更新检测（依赖 version-rocket）。

六、3.x：主题重构、图标优化与首屏性能冲刺

3.x 系列（2022）重点解决样式体系与打包性能，多次出现"首屏请求减少"级别的优化记录。

• 首屏优化：3.9.0 对比此前版本首屏请求减少 71 个、加载资源减少 4.1 MB；3.8.5 移除 @pureadmin/components 后未启用压缩前体积减少 0.4 MB、首屏请求减少 2.3 MB 资源；3.9.4 移除 vxe-table 后整体打包减少 1.82 MB；3.8.7 使用 unplugin-vue-define-options 替换 unplugin-vue-macros，完整版打包时长从约 6 分钟降至约 50 秒；
• 主题体系：3.3.0 重构主题色并适配 element-plus 暗黑模式（当前暗黑样式见 src/style/dark.scss）；2.8.0 引入暗黑主题与 element-plus 自定义主题；
• 图标体系：2.9.0 起采用 iconify 按需引入图标，2.8.5 起使用 @iconify-icons/ep 替换 @element-plus/icons-vue，3.9.3 扩展本地图标使用方式使首启动再减少 13 个请求，3.7.0 起支持 MenuArrowIconNoTransition 全局配置解决菜单展开卡顿；
• 工程决策：3.9.5 完全移除 lodash 及其相关库（改用 lodash-unified 等替代）；3.6.2 统一 @/ 别名替换 @/@/；3.6.1 添加 CDN 打包替换本地库开关与 gzip/brotli 压缩模式；3.5.0 使用 tailwindcss 替换 unocss；3.4.0 优化 query/params 路由传参（刷新页面无需开启标签页缓存也能保留参数）；3.6.0 重构权限模块为 RBAC 模型并更新页面/按钮权限示例。

七、2.x：导航模式、国际化与存储体系奠基

2.x 系列（2021-04 ~ 2022-02）确立了平台的骨架：

• 2.0.0 发布首个版本；2.0.1 添加 horizontal 水平模式导航；3.0 添加混合导航（对应 src/layout/components/lay-sidebar 下的 NavHorizontal/NavMix/NavVertical 三套导航）；
• 2.1.0 添加路由动画（每个路由可配置不同动画）与额外图标（菜单右上角新页面标记）；
• 2.6.0 重构导航主题色支持多配色、重构插画风格登录页（对应 src/assets/login）；
• 2.7.0 新增标签页复用、消息提醒模板、前端菜单树结构例子；重构 env 与 http 请求；本地存储确立 responsive-configure、responsive-locale、responsive-layout、responsive-tags 四个内置键（对应 public/platform-config.json 的 ResponsiveStorageNameSpace 命名空间体系）；
• 2.8.0 添加暗黑主题、引导页，优化国际化兼容 i18n Ally 插件（i18n 配置见 src/plugins/i18n.ts，语言文件位于 locales）；
• 2.9.0 添加打包大小分析命令 pnpm report，该命令至今保留在 package.json。

八、从 CHANGELOG 提炼的技术决策与升级启示

1. 构建链决策的演进逻辑

vue-pure-admin 的构建链选择呈现出清晰的跟随上游节奏：vite4 → vite5 → vite6 → vite7 → vite8，伴随 Rolldown/Oxc 的引入；同时坚持 ESM 优先，连配置文件也统一为 ESM 语法。对二次开发者而言，node/pnpm 版本要求（package.json）必须与主仓库保持一致，否则 preinstall 钩子（only-allow pnpm）会直接拦截。

2. 缓存与标签页是高频问题域

从 2.7.0 的标签页本地存储强制关联，到 4.x 密集修复 keepAlive 缓存边界，再到 6.x 完善缓存与标签激活逻辑，标签页体系是迭代最频繁的模块之一。核心实现在 src/store/modules/multiTags.ts 与 src/router/utils.ts 的 handleAliveRoute，配置项 MultiTagsCache、KeepAlive 位于 public/platform-config.json。

3. 权限与认证是业务接入重点

RBAC 权限 + 无感刷新 Token 是接入后端时必须完整理解的两套机制：页面权限在路由守卫判断、按钮权限有三种判断模式、token 刷新在 src/utils/http/index.ts 请求拦截器内闭环处理，模拟接口见 mock/refreshToken.ts。接入真实后端时，仅需按 src/utils/auth.ts 中 setToken 的注释调整 expires 时间格式即可。

4. 组件生态与示例库的定位

平台组件（RePureTableBar、ReVxeTableBar、ReDialog、ReDrawer、ReSegmented 等）是业务层复用的主力，而 @pureadmin/table、@pureadmin/utils、@pureadmin/descriptions 等库外置独立维护（见 package.json），与主仓库解耦更新。新增功能的惯例是"组件 + 示例页面"成对落地，可直接在 src/views/components 下找到对应演示代码。

结语

从 2021 年的 2.0.0 到 2026 年的 7.0.0，vue-pure-admin 的 CHANGELOG 完整记录了一条"性能优先、规范先行、体验精细"的演进路线：构建链全面现代化、全面 ESM 化、RBAC 权限与无感刷新 token 落地、标签页缓存体系成型、组件与示例库持续扩充。对于使用者而言，本文梳理的版本脉络与源码落点（public/platform-config.json、src/router/index.ts、src/utils/http/index.ts、src/utils/auth.ts 等）可以直接作为升级评估、二次开发与代码走读的索引；对于希望理解现代后台管理框架演进逻辑的开发者，这份 CHANGELOG 本身也是一份难得的工程决策实录。