开源项目第192期：shadcn-admin — Vite + shadcn/ui 构建的后台管理界面参考集

冬奇Lab 2026-08-20 0 阅读6分钟

引言

"每次做项目都要重新搭后台 UI，干脆把这些页面整理成一个可复用的参考集。"

这是「每日一个开源项目」系列的第 192 篇。今天的项目是 shadcn-admin —— satnaing 开源的后台管理界面参考集，基于 shadcn/ui + Vite + TanStack Router 构建。

13,900 颗 Star，MIT 许可。

先说清楚定位：README 里明确写着"This is not a starter project (template) though."——这不是一个开箱即用的脚手架，而是一套 UI 参考集合，展示如何用 shadcn/ui 组合出常见的后台管理界面。你可以直接 clone 来看效果、借鉴结构、复用组件，但它没有配好后端接口、没有业务逻辑，不能直接当项目模板用。

这个定位反而让它更有价值：干净、专注 UI、没有业务耦合。

你会学到什么

• 为什么选 Vite + TanStack Router 而不是 Next.js
• shadcn/ui 的底层逻辑：为什么它不是"组件库"
• 项目包含的 10+ 页面和核心组件
• RTL 支持的实现方式
• 与 Ant Design / MUI 后台模板的差异

前提知识

• 了解 React 基础
• 用过 Tailwind CSS
• 知道 shadcn/ui 是什么（或愿意了解）

---

先理解 shadcn/ui

shadcn/ui 经常被误解为"一个组件库"，安装后 import 使用。它不是。

shadcn/ui 的模式是：把组件源码直接复制到你的项目里。

npx shadcn@latest add button
# 执行后，Button 组件的完整源码出现在你的 src/components/ui/button.tsx
# 这个文件完全属于你，可以随意修改

底层是 Radix UI（提供无障碍交互逻辑）+ Tailwind CSS（提供样式）。你拿到的是可以直接编辑的源代码，不是封装好的黑盒。

这个模式的直接结果：样式完全可控，无障碍访问开箱即有，Bundle 里只有你实际用到的组件。

shadcn-admin 建立在这个基础上，因此整个项目的组件层都是透明可改的。

---

为什么是 Vite 而不是 Next.js

绝大多数后台管理模板用 Next.js。shadcn-admin 选择了 Vite + TanStack Router，理由很直接：

后台管理系统通常不需要 SSR。

大多数内部工具、管理后台都是需要登录才能访问的 SPA——没有 SEO 需求，没有首屏 SSR 加速的收益，反而带着 Next.js 的服务端复杂性（API Routes、Server Components、服务器部署需求）。

Vite 构建的纯前端 SPA：

• 构建速度快（HMR 毫秒级）
• 部署简单（静态文件，Netlify/Vercel/CDN 都行）
• 没有 Node.js 服务器依赖
• Bundle 更小

TanStack Router（前身是 React Router v6 的增强版）提供了类型安全的路由，在 TypeScript 项目里比 Next.js App Router 的文件路由更易控制。

---

页面结构

已认证路由（登录后可访问）

页面	å† å®¹
Dashboard	数据概览，统计卡片，图表，近期活动
Tasks	任务列表，过滤、排序、状态管理，DataTable 组件展示
Users	用户管理，搜索、分页、角色列表
Chats	即时消息界面，对话列表 + 聊天区
Apps	应用/集成管理页
Settings	多 Tab è®¾ç½®ï¼šè´¦æˆ·ã€é€šçŸ¥ã€å¤–è§‚ã€æ˜¾ç¤ºã€å®‰å ¨ã€å¿«æ·é”®
Help Center	帮助文档/FAQ 页

认证页面

• 登录（Sign In）
• 注册（Sign Up）
• 忘记密码（Forgot Password）
• OTP 验证
• 另有 Clerk 认证集成版本（/clerk 路由下）

错误页面

• 401 未授权
• 403 禁止访问
• 404 页面不存在
• 500 服务器错误
• 503 服务不可用

---

核心组件

侧边栏导航

使用 shadcn/ui 内置的 Sidebar 组件，可折叠，支持嵌套菜单，配合顶部 Header 构成完整的页面框架。

全局搜索（Command）

Cmd+K（macOS）/ Ctrl+K 呼出全局搜索命令面板，基于 shadcn/ui 的 <Command> 组件，支持键盘导航。这是后台系统里高频但经常被忽视的功能。

DataTable

基于 TanStack Table（前身 React Table）封装的数据表格：

• 列排序
• 多条件过滤
• 分页控制
• 行选择
• 列显示/隐藏切换

Tasks 和 Users 页面都用这个组件，是后台开发最常用的复杂组件之一。

主题切换

亮色/暗色模式切换，使用 CSS 变量驱动，shadcn/ui 的标准方案。

---

RTL 支持

这是 shadcn-admin 区别于大多数同类项目的功能——对阿拉伯语、希伯来语、波斯语等从右到左书写语言的完整支持。

实现方式不是简单地加一个 dir="rtl" 属性，而是对多个 shadcn/ui 组件进行了针对性的定制修改：

专项 RTL 改造的组件： alert-dialog、calendar、command、dialog、dropdown-menu、select、table、sheet、sidebar、switch

这些组件在 RTL 模式下有方向性的 UI 元素（图标位置、下拉方向、动画方向等），需要单独处理。

注意：如果后续用 npx shadcn add 更新这些组件，会覆盖 RTL 改动，需要手动合并。

---

安装和使用

git clone https://github.com/satnaing/shadcn-admin.git
cd shadcn-admin
pnpm install
pnpm run dev

Clerk 认证集成需要配置环境变量：

cp .env.example .env
# 填入 Clerk 的 PUBLISHABLE_KEY 和 SECRET_KEY

不用 Clerk 的话，项目里有不依赖 Clerk 的认证页面版本（/sign-in、/sign-up 等），直接用就行。

---

shadcn-admin vs 常见后台模板

维度	shadcn-admin	Ant Design Pro	AdminLTE
UI 基础	Radix UI + Tailwind（无样式组件）	Ant Design（重样式）	Bootstrap
æž„å»ºå·¥å ·	Vite	Umi.js	Webpack
路由	TanStack Router	Umi 路由	无（jQuery 时代）
RTL	深度支持	基础支持	有限支持
无障碍	Radix UI 原生保证	部分支持	基础
定制自由度	极高（组件源码在你项目里）	受限（import 黑盒）	受限
TypeScript	完整支持	完整支持	æ—
定位	UI 参考集合	生产脚手架	生产模板
Stars	13.9k	37k+	11k+

---

项目地址与资源

• GitHub: satnaing/shadcn-admin
• 在线预览: shadcn-admin.netlify.app
• 作者: satnaing（@satnaing）

---

总结

shadcn-admin 的价值在于它的定位选择：不做脚手架，做参考集。

大多数后台模板追求开箱即用，代价是耦合了大量你不需要的东西——认证方案、状态管理、API 层、权限系统……一旦你的需求和模板的预设不同，改造成本比从零开始还高。

shadcn-admin 只给你 UI 层——精心实现的界面结构、组件组合方式、响应式布局，以及 RTL 等细节处理。业务逻辑自己决定怎么加。

Vite + TanStack Router 的技术选型让它比 Next.js 模板更轻，适合后台管理这类 SEO 不重要、部署简单优先的场景。shadcn/ui 的"源码归你"模式保证了定制自由度。

13,900 Stars 说明这个方向是对的：开发者要的不是又一个捆绑了一切的后台框架，而是一套干净的 UI 参考，自己决定怎么组合。

---

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。