SoybeanAdmin：Vue3 中后台管理模板，从文件路由到权限模式一次讲透

SoybeanAdmin：Vue3 中后台管理模板，从文件路由到权限模式一次讲透

【免费下载链接】soybean-adminA clean, elegant, beautiful and powerful admin template, based on Vue3, Vite7, TypeScript, Pinia, NaiveUI and UnoCSS. 一个清新优雅、高颜值且功能强大的后台管理模板，基于最新的前端技术栈，包括 Vue3, Vite8, TypeScript, Pinia, NaiveUI 和 UnoCSS。项目地址: https://gitcode.com/GitHub_Trending/soy/soybean-admin

SoybeanAdmin 是一个基于 Vue3 + Vite8 + TypeScript + NaiveUI + UnoCSS 的中后台管理模板，帮做管理后台的开发者省掉布局、主题、路由权限、国际化这些脚手架层的重复劳动，clone 下来填业务页面就能跑。

快速上手：环境要求 Node >=20.19.0、pnpm >=10.5.0（package.json的engines字段写死），然后：

git clone https://gitcode.com/GitHub_Trending/soy/soybean-admin pnpm i pnpm dev

开发服务器起在 9527 端口，打开浏览器就能看到登录页。官方还提供在线预览：admin.soybeanjs.cn，另有 AntDesignVue、ElementPlus 两个 UI 版本可以按团队组件库习惯二选一。

文件路由：新增页面不用手动改 router

做过的后台项目大多有这么个痛点：每加一个页面，要建 vue 文件、在 routes 里注册、补 path 和 name，多个人同时提交时 routes 文件还是高频冲突点。SoybeanAdmin 用 Elegant Router 把这事自动化了：你只要在src/views/下按目录建组件，工具会扫描文件结构，自动生成路由导入、声明和类型，落在src/router/elegant/目录下——imports.ts是路由 key 到组件的映射，routes.ts是生成的常量路由，transform.ts负责把布局组件（layout.base）和页面组件（view.home）拼装成 vue-router 能吃的结构。改完文件跑一次pnpm gen-route即可，页面名、path、跳转函数都有类型提示，手敲路由名拼错在编译期就会报错。

权限路由：前端静态、后端动态两种模式

模板在src/router/routes/index.ts里把生成路由按meta.constant拆成constantRoutes（登录页、404 这类免登录）和authRoutes（需鉴权）两组，登录守卫在src/router/guard/route.ts里做拦截。关键点是它同时支持两种模式：静态模式下菜单和路由写死在前端，适合小团队快速上线、没有独立权限服务的场景；动态模式下后端返回菜单树，前端按数据渲染路由和侧边栏，适合按钮级权限、多角色租户这类要求后端说了算的场景。切换模式改环境变量即可，不用动路由结构。另外它内置了 iframe 页面路由（/iframe-page/:url），把第三方内嵌页拉进统一布局，这个细节很多模板要自己补。

主题预设：一套配置管布局和换肤

主题相关的配置集中在src/theme/目录：preset/下放了default、dark、compact、azir四套 JSON 预设，每套覆盖布局模式（vertical / horizontal / 双端混合）、头部/页脚显隐、tab 样式（chrome / slider / button 三种标签页形态）、侧边栏宽度、圆角、主题色这些项，一个 JSON 就是一份"外观皮肤"。运行时可以在页头打开主题抽屉实时切换，配置写入本地存储持久化。配色不是写死的——主色由@sa/color包基于主题色生成整套色阶，换成品牌色时不用手动调十几处 CSS 变量。

Mock 方案：默认连 ApiFox 在线服务，本地开发不用起后端

接口层用@sa/axios封装，src/service/request/index.ts里可以看到请求头带着apifoxToken，说明默认 mock 走的是 ApiFox 的在线 mock 服务，clone 下来pnpm dev就能跑通登录和首页数据，不需要先搭一套本地 mock 服务。token 过期自动刷新、登出码分级处理（静默登出 / 弹窗登出）这些逻辑也封装在onBackendFail钩子里，接真实后端时主要改.env里的 baseURL 和成功码约定。

落地场景与选型判断

中后台 CRUD 系统：这是它最合适的场景。布局、tab、面包屑、搜索、权限、异常页全是现成的，团队把精力放在业务组件上，两周内交付一个能用的管理端不难。

多语言产品后台：src/locales/内置 zh-CN / en-US 两套语言包，vue-i18n 接入，切语言是页面右上角一个开关，不用额外接插件。

不适合谁：如果你要的是纯组件库而不是完整框架，或者团队主栈是 React（它有个非官方 React 移植版 skyroc-admin，成熟度远不如原版），又或者你的后台对浏览器兼容性要求到 IE——官方明确不支持 IE，只覆盖各浏览器最近两个版本——那它都不合适。横向对比：vben-admin 偏"重型脚手架"、功能面更宽但学习曲线更陡；SoybeanAdmin 走的是克制路线，功能够用但边界清晰，代码量小很多，适合想读懂模板再动手的团队。

上手成本与踩坑提示

• 必须用 pnpm，npm/yarn 装不了：它是 pnpm monorepo，packages/下 8 个内部包（axios、alova、color、hooks、materials、scripts、uno-preset、utils）靠workspace:*协议引用。
• Node 版本门槛不低：>=20.19.0，pnpm >=10.5.0，老环境的 CI 机器要先升级。
• mock 依赖外网：默认请求头带 ApiFox token 连在线 mock，内网环境或想关 mock 时，按.env里的VITE_HTTP_PROXY切换代理策略，或把请求指向真实后端。
• pre-commit 钩子较严：simple-git-hooks配了typecheck + lint + fmt，首次本地提交可能要先跑通全量类型检查，慢网络下别以为是卡死。
• 业务代码和模板代码混在同一仓库：模板本身迭代快（当前 2.2.0，Vite 已经 8 了），后续升级版本时合并冲突集中在src/公共层，建议团队约定好哪些目录只放业务代码。

总结

一句话：要快速起一个 Vue3 中后台、且希望布局/主题/权限/国际化这些底座不写代码，SoybeanAdmin 目前是这类模板里工程质量最干净的选项之一。建议先花半小时把src/router/和src/theme/preset/两个目录读一遍，理解它的路由生成和主题预设机制，再决定哪些部分保留、哪些按业务改掉；对模板行为有疑问，仓库的 issue 区响应较快，值得先搜一下再提问。

【免费下载链接】soybean-adminA clean, elegant, beautiful and powerful admin template, based on Vue3, Vite7, TypeScript, Pinia, NaiveUI and UnoCSS. 一个清新优雅、高颜值且功能强大的后台管理模板，基于最新的前端技术栈，包括 Vue3, Vite8, TypeScript, Pinia, NaiveUI 和 UnoCSS。项目地址: https://gitcode.com/GitHub_Trending/soy/soybean-admin