Shadcn/UI 默认改用 Base UI 组件

背景

shadcn/ui 自 2023 年 1 月发布以来，一直基于 Radix 构建。Radix 是一套无样式、无头（headless）的 UI 组件库，API 设计优秀、可访问性强，且经过数百万应用的生产验证。当时市场上没有其他方案能与之匹敌。

然而，Radix 的原班团队后来开始开发一个全新的项目 —— Base UI。他们用第一次积累的经验，重新打造了这套组件库。去年（2025 年），Base UI 发布了 beta 版本，社区中很多用户开始询问 shadcn/ui 是否会替换掉 Radix。当时 shadcn/ui 团队给出的回答是：“对于生产应用来说，最糟糕的事情就是切换组件库。” 这个原则今天依然成立。

但团队没有选择直接“切换”，而是采用了 shadcn 一贯的做法：为 Base UI 重新构建每一个组件，保持相同的抽象层，让用户自行选择。2025 年 12 月，npx shadcn create 同时支持了两个库；2026 年 1 月，Base UI 的完整文档上线。团队观察了用户的选择趋势，最终在今天（2026 年 7 月）做出了正式变更。

核心内容

自 2026 年 7 月起，Base UI 已成为 shadcn/ui 的默认组件库。

为什么现在切换？

• Base UI 已经稳定，当前版本为 1.6.0，周下载量超过 600 万。
• 团队持续改进，定期发布新的实用组件。
• shadcn/ui 团队自己的新项目全部使用 Base UI。
• 用户已经用行动表态：通过 npx shadcn create 创建的新项目中，选择 Base UI 与 Radix 的比例为 2:1。社区已经做出了决定，团队只是将其正式化。

具体变化：

• 新项目执行 npx shadcn init 时，Base UI 成为默认选项。
• shadcn/create 界面中 Base UI 排在首位。
• 文档默认展示 Base UI；组件页面默认打开 Base UI 标签页，Radix 文档只需点击一次即可切换。

对现有用户的影响：

• Radix 不会被弃用。团队仍然支持它，每个更新和新组件都会同时为两个库推出（除非某个组件仅存在于 Base UI）。
• 无需迁移。Radix 是成熟且经过测试的库，团队自己仍在生产环境使用它，不会迁移。如果您的应用正常工作，请继续使用。
• 如果新项目仍想用 Radix，只需添加一个标志：在 shadcn init 后加上 -b radix。如果脚本或 CI 以非交互方式运行 shadcn init，并期望使用 Radix，请添加该标志以保持原有路径。
• 如果您在构建 registry，可以发布 registry:base 配置来固定特定库。没有此项的条目现在默认初始化为 Base UI。

关于迁移： 团队明确表示“你不需要迁移”。但如果用户希望迁移，shadcn/ui 提供了一个专门的“技能”（skill）——一种供 AI 编码助手（如 Claude Code、Cursor 等）使用的知识文件。

为什么用技能而不是 codemod？因为用户自己修改了代码（添加变体、修改类名、传递新属性）。Codemod 只能处理从未被改动的组件，而用户改过的部分会出问题。因此团队交付的是知识：每个重命名、每个属性变化、每个行为差异，都对照两个库手动验证过。AI 代理读取该知识后，能理解用户所做的改动，并将这些改动迁移过去。

迁移过程是渐进式的：一次只迁移一个组件及其使用位置，同时保持项目绿色可用。两个库可以共存。用户可以中途停止、发布版本，下周再继续。也可以要求一次性完成整个项目。

迁移每次运行会产生三样东西：

1. 可工作的代码：通过类型检查并构建成功后才报告成功。
2. 每组件报告：位于项目根目录的 .migration/ 文件夹中，记录哪些改动、哪些保持不变，以及需要人工验证的检查清单。
3. 干净的 Git 历史：每个组件一个提交，放在独立分支上，回滚只需删除分支。

报告示例：

.migration/button.json、.migration/dialog.json 等。

无隐藏状态。进度保存在文件系统和 Git 历史中，任何 AI 代理、任何会话、任何一天都能从中断处继续。

该技能适用于 Claude Code、Cursor 或任何支持 skills 的代理。团队在真实项目上测试过：60 多个组件（其中 36 个基于 Radix）的完整迁移大约耗时 25 分钟，每个组件约 10k tokens，构建干净，自定义修改保留完好。

关键要点

• 默认组件库已变更：2026 年 7 月起，shadcn/ui 新项目默认使用 Base UI 而非 Radix。
• Radix 仍然受支持：不会被弃用，所有更新和新组件将同步支持两个库。
• 无需强制迁移：现有 Radix 用户无需任何操作；团队自身也在继续使用 Radix 生产环境。
• 新项目默认 Base UI：npx shadcn init 自动选择 Base UI，旧项目用户可通过 -b radix 标志继续使用 Radix。
• 迁移工具为 AI skill：不是 codemod，而是提供给 AI 编码代理的知识文件，能保留用户自定义修改。
• 迁移过程渐进、可控：一次一个组件，两个库共存，生成独立分支报告，随时可中断继续。
• 迁移结果透明：每组件生成报告，包含改动清单和人工验证检查项，Git 历史干净易回滚。
• 社区已用脚投票：新项目中 Base UI 与 Radix 的选择比例为 2:1。

意义与影响

这次默认库的切换标志着 shadcn/ui 生态系统的重大转向。Base UI 由 Radix 原班团队基于多年经验重新打造，在稳定性（1.6.0 版本，600 万+周下载量）、组件丰富度和开发体验上已经得到社区验证。选择 Base UI 作为默认，既是对其成熟度的认可，也反映了社区的实际偏好。

对于现有 Radix 用户，shadcn/ui 团队采取了极为务实和低风险的策略：不强制迁移、不弃用 Radix、保持双库同步更新。这消除了大多数用户的生产顾虑，使得切换可以按照自己的节奏进行。

迁移工具的设计思路值得关注：放弃传统 codemod，转而采用 AI 代理可读的“技能”知识文件。这解决了 codemod 无法处理用户自定义代码的痛点，使得迁移过程更具智能性和灵活性。渐进式迁移（每组件独立提交、独立分支）也让回滚和调试变得异常简单，降低了采用门槛。

从更广的视角看，这一决策可能加速 Base UI 在更广泛 React 生态中的普及，同时也展示了 shadcn/ui 团队“不锁定用户、赋予开发者控制权”的理念——默认变了，但选择权始终在用户手中。未来，随着 Base UI 优势的进一步显现（如更清晰的 API、更多内置组件），Radix 可能逐渐退居次要位置，但团队承诺的双库同步策略确保了平稳过渡。