从零搭后台管理前端模板（SoybeanAdmin）

新开一个后台项目，前端总要重搭一遍：左边菜单、顶部标签、路由注册、登录失效跳转、表格分页、主题色。这些东西每个团队都写过很多次，写的时候没有产出感，交给产品看还要被嫌不好看。SoybeanAdmin 把这一整套做成了开箱可用的模板，仓库在 soybeanjs/soybean-admin，采用 MIT 许可证，主要语言 TypeScript，Star 15051、Fork 2516，最近一次提交在 2026-10-06。

SoybeanAdmin 是一套用 TypeScript 和 Vue 3 写的后台管理前端模板，输入是 pnpm 工程与接口约定，输出是可直接构建部署的后台界面。

技术栈固定在 Vue 3、Vite 8、TypeScript、Pinia、NaiveUI 和 UnoCSS 这一组上。它给出的只是前端，后端接口得自己接。README 的「周边生态」里列了十来个社区写的适配后端，包括 pea、MalusAdmin、PanisAdmin、soybean-admin-go、ba、FastSoyAdmin 等，这些都不是官方维护的。仓库还按 UI 库分出了 AntDesignVue 版本和 ElementPlus 版本，各自有独立仓库与预览地址，旧版代码留在 legacy 分支。

它怎么做到的

路由是这个项目里最核心的一条链路。src/views 下的文件按约定组织，构建过程中自动生成路由的导入、声明与类型，开发者不用再手写路由表。这套机制由同团队的 Elegant Router 实现，README 里把它列在「自动化文件路由系统」这一条特性下，细节指向独立仓库。

仓库顶层有 build/、packages/、src/、public/ 和 docs/ 几个目录，配合 pnpm-workspace.yaml 组成一个 pnpm monorepo。配置集中在根目录：vite.config.ts、uno.config.ts、tsconfig.json、eslint.config.js、.oxlintrc.json、.oxfmtrc.json，以及 .env、.env.prod、.env.test 三份环境文件。

数据这一头，开发阶段用的是基于 ApiFox 的在线 Mock 方案。README 没有展开说明这套 Mock 怎么落到本地、内网或离线环境怎么替换。构建只写了 pnpm build 一条命令，产物目录、部署方式和默认端口，仓库里同样没有说明。

几个关键设计

文件即路由（Elegant Router）

页面文件放进约定的目录，路由、类型和导入语句自动生成，省掉了手写路由表这一步。代价是这套约定藏在构建流程里：issue 里有用户专门问「如何关闭自动生成路由」，这条讨论累积了 13 条评论，说明想绕开它的人不算少。README 没有给出关闭自动生成路由的配置项。

pnpm monorepo 与内部分包

axios 封装、hooks 这类公共能力被拆成 @sa/axios、@sa/hooks 这样的内部包，放在 packages/ 下，由 pnpm workspace 统一管理。v2.0 的计划清单里明确列了这两项的优化。拆包的好处是复用边界清楚，改动的代价在后面一节说。

主题与 UnoCSS 样式层

主题配置做成了一个独立的配置组件，配合 UnoCSS 统一原子类。v2.0.1 的更新说明里提到主题预设支持只设置部分内容，也就是说不必每次都写全量配置。v2.1.0 里表格的列设置开始支持固定列。样式层和主题配置的字段清单，README 没有逐一列出。

权限路由、内置页面与数据来源

权限路由同时支持前端静态路由和后端动态路由两种方式，具体接哪一种由后端接口决定。内置的页面与组件包括 403、404、500 三个错误页，以及布局组件、标签组件和主题配置组件。国际化方案内置，移动端做了自适应布局，README 称其「完美支持移动端」，实际断点与适配范围文档里没有给出参数。

命令行工具覆盖 git 提交、删除文件、发布等操作，README 只给出了 pnpm commit 这一个具体命令，用来生成符合 Conventional Commits 规范的提交信息。其余命令的名字与参数仓库里没有列全。

这样设计的代价

第一道门槛在环境。运行要求是 NodeJS >= 20.19.0、pnpm >= 10.5.0，README 明确写了不要用 npm 或 yarn 安装依赖，因为整个仓库是 pnpm monorepo。v2.2.0 把 pnpm 从 v10 升到 v11，这一条被标成破坏性变更，机器上锁着旧版 pnpm 的团队要跟着升级。

第二道门槛在依赖体积。issue 里有人截图反馈引入的 icons 相关插件过多、安装依赖特别大，怀疑存在冗余，这条已经解决，问题本身说明模板的依赖量级比一个手搭的轻量项目要大。

第三是改动的波及面。公共逻辑拆进 @sa/* 内部包，改一处 axios 拦截或 hooks 行为，影响的是所有用到它的页面，分包并没有让改动变局部。

第四是版本与分支的错位。项目经历过一次整体重构（issue #277），重构前的代码留在 legacy 分支且转为低频更新。main 分支还被精简成只保留首页菜单，其余示例挪到 example 分支维护。照文档截图去 main 分支找对应页面，很可能找不到。

第五是 Mock 方案的外部依赖。开发数据走的 ApiFox 在线 Mock，如果团队在内网、或者不想把接口结构放到第三方平台上，切换路径需要自己补，仓库未展开说明。

同类后台模板对照

如果你的团队不接受 pnpm 工作流，或者只需要几张配置化的 CRUD 页面，SoybeanAdmin 这一整套路由、权限、主题、国际化带来的上手成本是实打实的负担，体量更小的模板会更直接。同表里的两个对比项社区规模小、文档少，选它们意味着遇到问题时能查到的答案更少；SoybeanAdmin 的短板则在于强制 pnpm 和只做前端，需要完整前后端一体的方案时，得去 README 的周边生态里自己拼，那些项目都不是官方维护的。

对你的实际影响

环境准备这一步没有商量余地，NodeJS 建议 20.19.0 或更高，pnpm 建议 10.5.0 或更高，git 用于克隆仓库。

git clone https://github.com/soybeanjs/soybean-admin.git
cd soybean-admin
pnpm i
pnpm dev
pnpm build

pnpm i 装依赖，pnpm dev 起本地开发服务器，pnpm build 出构建产物。README 没有写开发服务器的默认端口，也没有写构建产物落在哪个目录，这两项要跑起来自己看终端输出。仓库同时提供 Gitee 和 Gitcode 的克隆地址，国内网络拉不动 GitHub 时可以换。

配置层面，根目录有 .env、.env.prod、.env.test 三份环境文件，分别对应默认、生产、测试环境。README 的安装章节没有列出这些文件里的变量名和取值含义，改之前得自己打开看。

项目还有一份体量不小的变更记录，CHANGELOG.md 有 283.4 KB，中文版 CHANGELOG.zh_CN.md 有 42.9 KB，升级前翻一下能省掉不少排查时间。

实际使用中踩过的坑，可以从 issue 里挑几条典型的看：封装的 table 组件默认按 records 字段取数据，后端如果直接返回数组、或者数据需要二次处理，就得改适配逻辑，这条讨论有 17 条评论，现已解决；页面长时间不操作、后端返回 401 时，跳转登录页会卡在 loading 状态，现已解决；登录后点浏览器刷新，userInfo 变成空、没有 roles，导致首页路由判断出错，现已解决；对 window 对象做的 TS 类型扩展在 WebStorm 里无法解析，现已解决。这四条的共同点是都发生在接入自有后端之后，用 Mock 数据跑 demo 时碰不到。

这套模板适合手上要起 Vue 3 后台、又不想从零写布局和权限的团队，尤其是已经用 NaiveUI 或打算用 UnoCSS 的项目组。它不适合坚持用 npm 或 yarn 的团队，不适合需要后端和数据库一起交付的场景，也不适合只想要一个轻量表格页、不愿意读一整套路由与主题代码的开发者。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.6 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。