后端零改动，给若依换一套现代化前端

RuoYi（若依） 大概是国内最流行的开源后台管理框架之一：RBAC 权限体系完善、代码简洁、文档与社区成熟，RuoYi-Vue 几乎成了「后台管理系统」的默认起手式。

但官方前端多年来停留在上一代的技术审美里：观感略显陈旧、主题定制能力弱（换个主色要改一堆 Less 变量）、布局单一、没有国际化。很多团队的真实状态是——后端用着若依，前端另起炉灶重写一遍，权限、字典、代码生成这些能力全部要重新对接。

于是就有了 ruoyi-vue-nys：一套适配若依后端 API 的现代化中后台前端。

后端零改动，前端整套替换。/getRouters、登录鉴权、字典、代码生成等接口全部原样对接；原有的业务页面、指令与全局方法直接可用，50 余个页面零改动迁移。

亮色主题 + 主题配置抽屉（主题模式 / 布局模式 / 主题色 / 页面功能一屏可调）：

用户管理页（亮 / 暗），组织机构树、搜索表单、分页、行内操作一应俱全：

项目通过 pnpm workspace 内置了 5 个 @sa/* 包：color（色板生成）、hooks、materials、utils、uno-preset，主题、布局、路由约定等基础架构参考了同样开源的 soybean-admin 体系。

res.rows、this.download、this.$modal、v-hasPermi……这些全是若依的「方言」。要零改动迁移，就必须把这些方言一模一样地在新技术栈上重新实现出来。

若依页面大量依赖全局方法。新框架把它们全部挂回去（src/plugins/ruoyi.ts）：

其中 $modal、$tab、$cache 这类「若依专属插件对象」也有讲究：比如 $tab.closePage() 要同时兼容新框架的多标签页与 KeepAlive 语义，$modal.msgSuccess() 内部则转译到 Element Plus 的 ElMessage。

若依页面用字符串引用图标（icon="Search"），这依赖图标被全局注册。最简单的做法是：

全量注册的代价是把 294 个图标约 300 KB 全部打进首屏 chunk，而项目实际只用到几十个。这里的做法是写一个生成脚本扫描源码，得出真实使用集合，只注册命中的图标（实测 55 个）：

还有一个隐藏坑：若依「表单构建」页用字符串 tag（'el-input'、'el-select'）动态渲染组件，如果为此把整套 Element Plus 全局注册一遍，这些组件会跟着入口文件一起进首屏。最终方案是让表单构建的画布自行映射这些动态组件，入口只保留按需引入。

请求层（src/utils/request.js）在移植时保留了这个契约，所以业务代码里的 res.rows / res.total 完全不用改：

若依的 /getRouters 返回 RouterVo 树：component 字段是字符串（Layout / ParentView / InnerLink / 视图路径），meta.noCache 控制缓存，一级菜单还会包一层 meta 为空的 Layout 壳。转换层（src/router/dynamic/ruoyi.ts）负责把它翻译成前端路由：

菜单管理里改一下菜单，刷新页面即时生效，无需重新构建。

@iconify/vue 默认在运行期向 https://api.iconify.design 拉取图标数据。这在内网 / 无外网环境会直接导致图标缺失——实测单次请求还要等约 7 秒。

解决方案是在构建前执行内联脚本，把项目实际用到的 27 个图标数据生成到 src/plugins/iconify.ts，随包发布、离线可用：

同时保留在线兜底：配置 VITE_ICONIFY_URL 指向自建 iconify 服务后，未内联的图标会自动回退到该地址拉取。新增图标只需在脚本清单里加一行、重新执行生成脚本即可。

主题配置在开发模式下不落缓存，改默认值立即生效；生产构建以 BUILD_TIME 作为覆盖标记，新版本发布后自动应用新的默认主题，不会被老用户的本地缓存「锁死」。

后端直接使用任意 RuoYi-Vue 3.9.x 版本（推荐 RuoYi-Vue-fast 单模块版），前端代理指过去即可，无需改动后端任何代码。

ruoyi-vue-nys 不是又一个「重新造轮子」的后台模板，而是一次接管式迁移：承认若依后端生态的价值，把前端从上一代技术栈整体搬到 Vue 3.5 + Vite + TS + UnoCSS 上，同时用兼容层保证业务页面零改动。

如果这个项目对你有帮助，欢迎 Star、提 Issue，或者直接提 PR。

GitHub：github.com/niyongsheng…

来源：稀土掘金　原文