shadcn/ui 完全上手指南：组件源码复制进你的 React 项目，2026 默认基元换 Base UI

shadcn/ui 最反直觉的一点：它不是 npm 依赖。你用 CLI 把组件源码直接复制进项目，之后代码就是你的，改什么都不受上游版本卡脖子，这是它和绝大多数组件库的根本区别。

它解决什么问题

传统组件库一旦升级改了 API，你的项目就可能跟着崩。shadcn/ui 把源码给你，版本锁死、上游变更你完全可控，升级与否由你自己决定。

代价是组件进你仓库后，要自己跟进更新、要懂 Tailwind。对只想装个包就完事的团队，它反而成了负担而不是便利。

核心能力

2026 年的底座切换意味着什么

2026 年 7 月起，shadcn/ui 默认组件基元从 Radix UI 换成 Base UI——社区投票约 2:1 选了 Base UI。Radix 并未被抛弃，用 -b radix 一条命令就能切回；React Aria 也成了可选底座（–base aria）。

对老项目影响不大：已复制进来的代码不受影响，新生成组件才走新默认。想保持一致就显式指定 -b radix；想用 React Aria 的无障碍能力就 –base aria。切换是逐步的，不是硬性断裂。

同类工具怎么选

谁适合用

• 想完全掌控组件代码、怕上游 Breaking 的 React 团队
• 已经用 Tailwind、希望组件样式和原有体系一致的人
• 做 AI 对话类产品、需要现成聊天界面组件的人

怎么开始

1. 确保项目已装 Tailwind CSS，再用 npx shadcn@latest init 初始化配置文件。
2. 用 npx shadcn@latest add button 这类命令把组件源码复制进 components/ui。
3. 想保持旧基元就加 -b radix；要用 React Aria 就加 –base aria 再 add。
4. 直接改复制进来的源码与 Tailwind 类，样式完全由你掌控。
5. 需要聊天界面就 add message-scroller / message / bubble / attachment。

常见问题

它是 npm 包吗？
不是。组件源码被复制进你的项目，归你所有，没有升级上游就崩的问题。

默认基元换了吗？
2026 年 7 月起默认从 Radix 换成 Base UI，Radix 仍可用 -b radix 切回。

团队不懂 Tailwind 能用吗？
能跑，但改样式会吃力；它本就是为 Tailwind 用户设计的。

适合大团队吗？
适合重视可控性的团队；想零维护装包的团队会更想要 MUI / AntD。

授权与合规

shadcn/ui 采用 MIT 授权，代码通过 CLI 复制到你的项目里、归你所有，可自由修改与商用，没有订阅或付费墙。 官网：ui.shadcn.com。