2026年7月 - 默认使用 Base UI

从今天开始，Base UI 是 shadcn/ui 的默认组件库。

先说一点历史。shadcn/ui 于 2023 年 1 月发布时，基于 Radix 构建。当时，没有其他方案能与之媲美。无样式的 headless 组件、出色的 API、优秀的可访问性，经过数百万应用的实战检验。

几年过去了，构建 Radix 的那些人正在做一些新的东西：Base UI。他们已经成功做过一次了。现在，他们可以把第一次学到的一切带着再做一次。

去年，Base UI 发布了 beta 版，很多人问我们是否会用它替换 Radix。我说过：“对你的生产应用来说，最糟糕的事情就是切换组件库。”我当时是认真的，而且现在依然如此。所以我们没有切换，而是做了 shadcn 风格的事情：我们为 Base UI 重建了每个组件，保持相同的抽象层，并让你自己选择。12 月推出了同时包含两个库的 npx shadcn create。1 月则带来了完整的 Base UI 文档。

然后我们观察了你用它做了什么。

为什么是现在#

• Base UI 已经稳定。 目前版本为 1.6.0，每周下载量超过 600 万。
• 它还在不断变得更好。 团队会定期发布新的实用组件。
• 我们自己也在用。 我们启动的每一个新项目都运行在 Base UI 上。
• 你也在用。 现在通过 shadcn/create 创建的项目，选择 Base UI 的比例已经以 2:1 超过了 Radix。

社区已经做出了选择。我们现在正式确认这一点。

有哪些变化#

• 新项目默认使用 Base UI。 运行 npx shadcn init，Base UI 将作为默认选项。
• shadcn/create 会优先显示 Base UI。
• 文档默认使用 Base UI。 组件页面会默认打开 Base UI 选项卡。Radix 文档只需点击一下即可查看。

这对你意味着什么#

Radix 并未被弃用。 我们仍然支持它，且每次更新和新组件都会同时为这两个库提供（除非某个组件只存在于 Base UI 中）。

你不需要迁移。 Radix 是一个成熟、经过测试的库。我们今天仍在生产环境中使用它，而且我们不会迁移。如果你的应用运行正常，就继续发布吧。

新项目更想用 Radix？ 只需一个标志：

pnpmnpmyarnbun
pnpm dlx shadcn init -b radix
Copy

如果你有脚本或 CI 在非交互式运行 shadcn init，并且期望使用 Radix，请添加 -b radix 以保持它们走同一路径。

在构建 registry？ 如果你想固定到某个特定库，请提供一个 registry:base 配置。现在没有该配置的条目会默认初始化为 Base UI。

准备开始新项目？ 我们推荐 Base UI。

当你准备好迁移时#

你不需要迁移。但如果你想，我们为此构建了一个 skill：

pnpmnpmyarnbun
pnpm dlx skills add shadcn/ui
Copy

然后让你的编码代理执行：

Copymigrate accordion to base-ui

它默认采用渐进式迁移：一次迁移一个组件及其使用方式，同时让你的项目保持绿色可构建、可交付。工作过程中两个库会并存。你可以中途停止、发布，然后下周回来时，它会从上次停下的地方继续。或者也可以一次性让它处理整个项目。

为什么用 skill，而不是 codemod？#

因为代码是你自己的。你加过变体、改过类名、传过新的 props。codemod 只能处理那些你从没碰过的组件，却会把你改过的地方弄坏。

所以我们改为提供知识：每一次重命名、每一次 props 变化、每一种行为差异，都经过两个库的人工核对。你的代理会读取这些信息，弄清楚 你 改了什么，并把这些改动一并迁移过去。

机械性的改动会在所有地方修复（asChild 现在是 render）。行为变化会被标记出来，而不会被悄悄修补。由你来决定。

一次迁移会产出什么#

每次运行都会留下三样东西：

• 可工作的代码。 在报告成功之前，已经通过类型检查并完成构建。
• 每个组件一份报告，位于你项目根目录下的 .migration/：改了什么、哪些没动，以及一份需要手动验证的简短清单。
• 干净的 git 历史。 每个组件一个 commit，放在一个分支上。回滚就是删除这个分支。

下面是报告的样子：

Copy# accordion
 
<!-- 日期、使用的策略，以及一句话结论 -->
 
## Changed
 
<!-- 所有被修改的文件，以及改动内容和原因 -->
 
## Left alone
 
<!-- 看起来相关但故意没有触碰的文件 -->
 
## Behavior changes
 
<!-- 能编译通过但行为不同的差异。会被标记，而不会被修补。 -->
 
## Verify by hand
 
<!-- 一个简短的检查清单：打开、点击、用 Tab 浏览。只需一分钟 -->

没有隐藏状态。进度保存在你的文件和 git 历史中，所以任何代理、任何会话、任何一天都能从上次停止的地方继续。

它可与 Claude Code、Cursor，或任何支持 skills 的代理配合使用。我们在真实项目上测试过：60+ 个组件，其中 36 个基于 Radix。一次完整迁移大约用了 25 分钟，每个组件大约 10k tokens。构建干净，定制内容完好保留。