Shadcn/UI 现在默认使用 Base UI 而非 Radix

# 更新日志 来源：https://ui.shadcn.com/docs/changelog ## 2026 年 7 月 —— Base UI 成为默认选项 从今天起，**Base UI 正式成为 shadcn/ui 的默认组件库**。 先简单回顾一下历史。shadcn/ui 于 2023 年 1 月发布时，构建在 Radix 之上。当时，没有其他库能与之媲美：无样式 Headless 组件、优秀的 API、出色的可访问性，并在数百万应用中得到过实战检验。 几年后，当初打造 Radix 的团队又推出了新作品：Base UI (https://www.base-ui.com/)。他们成功过一次，现在带着第一次积累的全部经验，再创辉煌。 去年，Base UI 发布了 Beta 版本，很多人问我们是否会用它替换 Radix。我当时说：“对于生产环境应用来说，最糟糕的做法就是更换组件库。” 我是认真的，现在依然如此。所以，我们没有进行替换，而是做了 shadcn 风格的事：为每个组件重新构建了 Base UI 版本，保持相同的抽象层，让你自己选择。十二月，我们推出了带两个库选项的 `npx shadcn create`；一月，Base UI 的完整文档上线。 然后，我们观察了你的使用情况。 ## 为什么是现在 (https://ui.shadcn.com/docs/changelog#why-now) - **Base UI 已稳定。** 目前版本号 1.6.0，周下载量超过 600 万。 - **它持续进步。** 团队定期发布新颖且实用的组件。 - **我们在用。** 我们启动的所有新项目都运行在 Base UI 上。 - **你在用。** 通过 shadcn/create 创建的项目中，选择 Base UI 的比例是 Radix 的两倍。 社区早已做出了选择，我们现在只是正式确认这个变化。 ## 有什么改变 (https://ui.shadcn.com/docs/changelog#whats-changed) - **新项目默认使用 Base UI。** 运行 `npx shadcn init` 后，Base UI 为默认选项。 - **shadcn/create 优先显示 Base UI。** - **文档默认展示 Base UI。** 组件页面默认打开 Base UI 选项卡，Radix 文档只需一次点击即可切换。 ## 这对你意味着什么 (https://ui.shadcn.com/docs/changelog#what-this-means-for-you) **Radix 不会被弃用。** 我们仍然支持它，每次更新和新组件都会同时为两个库发布（除非某个组件仅在 Base UI 中存在）。 **你无需迁移。** Radix 是一个成熟且经过充分测试的库。我们目前仍在其上运行生产环境，并且不打算迁移。如果你的应用运行正常，请继续交付。 **新项目更倾向 Radix？** 只需一个标志即可： 如果你有脚本或 CI 以非交互方式运行 `shadcn init` 并期望使用 Radix，请加上 `-b radix` 以保持原有路径。 **正在构建注册表？** 如果你希望固定使用特定库，请提供 `registry:base` 配置。没有此项的条目将默认初始化为 Base UI。 **正在启动新项目？** 我们推荐使用 Base UI。 ## 当你准备好迁移时 (https://ui.shadcn.com/docs/changelog#when-youre-ready-to-migrate) 你不需要迁移。但如果你想，我们为此构建了一个技能： 然后对你的编码助手说： `` migrate accordion to base-ui `` 它默认是渐进式的：一次只迁移一个组件及其使用方式，同时让你的项目保持可构建、可交付状态。两个库可以共存。你可以中途停止、交付，下周回来时它会从上次中断的地方继续。或者要求一次完成整个项目。 ### 为什么是技能而不是 codemod？ (https://ui.shadcn.com/docs/changelog#why-a-skill-and-not-a-codemod) 因为代码是你的。你添加了变体、修改了类、传递了新属性。Codemod 能处理你从未改动过的组件，但会在你改动过的组件上出错。 所以我们传递的是知识：每个重命名、每个属性变更、每个行为差异，我们都对照两个库手动检查过。你的编码助手读取这些知识，理解你改了哪些内容，并将这些改动迁移过去。 机械性的改动会被全局修复（`asChild` 现在变为 `render`）。行为变更会被标记，绝不会静默修补。由你决定。 ### 迁移会产生什么 (https://ui.shadcn.com/docs/changelog#what-a-migration-produces) 每次迁移运行后会留下三样东西： - **可工作的代码。** 在报告成功之前，代码会通过类型检查和构建。 - **每个组件的报告**，保存在项目根目录的 `.migration/` 文件夹中：什么变了，什么没变，以及一份简短的手动验证清单。 - **干净的 Git 历史。** 每个组件一个提交，位于一个分支上。回滚只需删除该分支。 以下是报告的样子： .migration/accordion.md`` # accordion <!-- 日期、使用的策略和一行总结 --> ## 已变更 <!-- 每个被修改的文件，以及修改了什么和原因 --> ## 未改动 <!-- 看起来相关但故意没有触碰的文件 --> ## 行为变更 <!-- 编译正常但行为不同之处。已标记，未修补 --> ## 手动验证 <!-- 简短清单：打开、点击、Tab 键逐项检查。约一分钟完成 --> `` 没有隐藏状态。进度保存在你的文件和 Git 历史中，因此任何代理、任何会话、任何一天都能从上一次中断的地方继续。 该技能兼容 Claude Code、Cursor 或任何支持技能的编码助手。我们在实际项目上测试过：超过 60 个组件，其中 36 个基于 Radix。完整迁移大约花费 25 分钟，每个组件约 1 万 token。构建干净，自定义内容完好保留。 ## 2026 年 6 月 —— 聊天界面组件 今天，我们发布了一套用于构建聊天界面的新组件：**MessageScroller** (https://ui.shadcn.com/docs/components/message-scroller)、**Message** (https://ui.shadcn.com/docs/components/message)、**Bubble** (https://ui.shadcn.com/docs/components/bubble)、**Attachment** (https://ui.shadcn.com/docs/components/attachment) 和 **Marker** (https://ui.shadcn.com/docs/components/marker)。 这是聊天组件工作的第一阶段。我们逐步推进，重新设计每个部分的抽象层，并以 shadcn/ui 组件的形式发布，你可以复制、组合并适配到自己的产品中。 我们从对话层开始：滚动、消息行、气泡、附件和标记。 我们问自己：什么造就了出色的流式聊天体验？然后我们将核心规则抽象为一组基础组件：`MessageScroller`。 `MessageScroller` 是聊天的滚动容器。它处理那些容易出错的细节：锚定跳转、流式回复、保存的对话恢复、前置历史记录、跳转到某条消息、滚动控制以及可见性追踪。 `MessageScroller` 管理这些行为，但不管理你的消息内容、AI 状态、传输层、持久化或模型状态。你只需要提供内容渲染器。 `MessageScroller` 也以无样式 headless 组件的形式存在于 `@shadcn/react` 中。 ## Message、Bubble、Attachment 和 Marker (https://ui.shadcn.com/docs/changelog#message-bubble-attachment-and-marker) 其余组件涵盖了滚动器周围日常所需的各个部分。 - `Message` 用于在对话中布局一行，包含头像、对齐方式、头部、内容、底部和分组消息。 - `Bubble` 渲染消息表面，支持变体、对齐、反应、链接、按钮和可折叠内容。 - `Attachment` 渲染文件和图片，包含媒体、元数据、上传状态、操作，以及一个保持操作独立可点击的全卡片触发器。 - `Marker` 用于渲染状态更新、系统通知、带边框的行以及带标签的分隔线，例如流式状态、工具活动和日期分隔符。 它们有意设计得小巧，可以组合用于 AI 聊天、客服收件箱、团队讨论、群聊以及特定产品的对话场景。 我们还添加了两个新的 CSS 工具函数，用于改善聊天界面的细节体验。 `scroll-fade` (https://ui.shadcn.com/docs/utils/scroll-fade) 为滚动容器添加了感知滚动位置的边缘淡出效果。可用于 `MessageScroller`、`ScrollArea`、附件行以及任何长列表，无需添加覆盖层或滚动监听器即可提示更多内容。 `shimmer` (https://ui.shadcn.com/docs/utils/shimmer) 为实时状态添加文字闪烁效果。可用于“思考中……”、“生成回复中……”、正在运行的工具和流式标记等。 这两个工具函数随 `shadcn/tailwind.css` 一起发布，因此通过 `npx shadcn@latest init` 初始化的项目已自带它们。 ## @shadcn/react (https://ui.shadcn.com/docs/changelog#shadcnreact) 我们还创建了 `@shadcn/react`，一个新的无样式、headless React 组件包。 第一个基础组件是 `@shadcn/react/message-scroller`。注册表组件使用 shadcn/ui 样式包装了它，但滚动行为（锚定、自动跟随、前置内容保留、滚动命令和可见性）都放在该包中。 这样，我们可以在不锁定视觉风格的情况下发布行为。你仍然可以获得与项目匹配的可复制粘贴组件，而复杂的交互逻辑则在同一位置经过测试。 现已同时支持 Radix 和 Base UI。 ## AI Elements (https://ui.shadcn.com/docs/changelog#ai-elements) 这并不会取代 AI Elements (https://ai-sdk.dev/elements/overview)。你可以继续使用 AI Elements 来处理 AI 界面组件和模式。本次发布是将聊天的核心组件逐步引入 shadcn/ui。 如果你已经在使用 AI Elements 中的某个组件，无需重写应用。保留能正常工作的部分。当你想要更新的抽象、更新的样式或同时支持 Radix 和 Base UI 时，可以尝试使用 shadcn/ui 版本。 目标是让这些组件易于独立采用。替换一部分，与你已有的组件组合，然后继续构建。 查看组件 (https://ui.shadcn.com/docs/components) ## 2026 年 6 月 —— GitHub 注册表 **现在你可以将任何公开的 GitHub 仓库变成注册表。** 在仓库根目录添加一个 `registry.json` 文件，定义要分发的内容项，用户即可通过 `shadcn` CLI 直接从 GitHub 安装。 例如，从 `acme/toolkit` 仓库安装 `project-conventions` 内容项： GitHub 注册表是源注册表。你不需要运行 `shadcn build`、发布生成的 JSON 文件或搭建注册表服务器。CLI 会读取根目录的 `registry.json`，解析 `include` 条目，找到请求的内容项，并安装该条目声明的文件。 ## 分发任何内容 (https://ui.shadcn.com/docs/changelog#distribute-anything) 注册表内容项不限于组件。GitHub 注册表可以分发组件、自定义 Hook、工具函数、设计令牌、功能套件、项目规范、编码助手指令、测试设置、CI 工作流、发布工作流、模板、codemod、迁移套件以及其他项目文件。 例如，一个仓库可以暴露一个 `project-conventions` 内容项，用于安装共享文档、编辑器设置和编码助手指令： registry.json`` { "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "acme-toolkit", "homepage": "https://github.com/acme/toolkit", "items": [ { "name": "project-conventions", "type": "registry:item", "files": [ { "path": "AGENTS.md", "type": "registry:file", "target": "~/AGENTS.md" }, { "path": ".editorconfig", "type": "registry:file", "target": "~/.editorconfig" }, { "path": "docs/conventions.md", "type": "registry:file", "target": "~/docs/conventions.md" } ] } ] } `` ## 命令 (https://ui.shadcn.com/docs/changelog#commands) GitHub 注册表地址与其他注册表地址使用相同的命令。 列出 GitHub 注册表中的内容项： 搜索内容项： 查看内容项： 安装内容项： 请参阅 GitHub 注册表文档 (https://ui.shadcn.com/docs/registry/github) 以获得完整指南。 ## 2026 年 5 月 —— shadcn eject 当我们添加对 Radix 和 Base UI 的双重支持时，需要一个共享 Tailwind 工具函数的地方，两个库都依赖这些工具，例如 `data-open:` 和 `data-closed:` 等自定义变体，以及 `no-scrollbar` 这类工具函数。 此外，在开发 RTL 支持时，我们遇到了几个 Bug，这些 Bug 在共享位置修复比在每个组件中重复修复更容易。 因此，我们创建了 `shadcn/tailwind.css`。当你运行 `init` 时，它会在全局 CSS 文件中添加 `@import "shadcn/tailwind.css"`。它与其他 CSS 导入（如 `tw-animate-css`）的工作方式相同：一个小的依赖项，在构建时会被 tree-shaking 处理。 如果你不想为了那部分 CSS 而依赖 `shadcn` 包，我们添加了 `shadcn eject` 命令。它会将 `shadcn/tailwind.css` 内联到你的全局 CSS 文件中，并从项目中移除 `shadcn` 依赖。 **之前** `` @import "tailwindcss"; @import "tw-animate-css"; @import "shadcn/tailwind.css"; `` **之后** `` @import "tailwindcss"; @import "tw-animate-css"; /* ejected from [email protected] */ @theme inline { @keyframes accordion-down { from { height: 0; } to { height: var( --radix-accordion-content-height, var(--accordion-panel-height, auto) ); } } } @custom-variant data-open { &:where([data-state="open"]), &:where([data-open]:not([data-open="false"])) { @slot; } } `` 在 monorepo 中，请从包含 `components.json` 和全局 CSS 文件的工作空间运行该命令： 请参阅 CLI 文档 (https://ui.shadcn.com/docs/cli#eject) 了解更多详情。 ## 2026 年 5 月 —— 引入 Rhea 介绍 Rhea，一种新的 shadcn/ui 样式。更紧凑的 Luma。更小的间距。更密实的表面。专为聚焦的产品界面而设计。 Rhea 样式预览 Rhea 样式预览 在 shadcn/create 中尝试 Rhea (https://ui.shadcn.com/create?preset=b27GcrRo) Rhea 源于一个我们经常听到的简单请求：Luma 但是更紧凑。我们观察了人们如何使用新样式以及他们的需求，模式很明显。许多团队希望保留 Luma 的柔和度和形状，但希望更紧凑的间距、更小的控件和更高的信息密度。 Rhea 保留了相同的圆角基础，但使其更紧凑，适用于空间至关重要的产品界面。按钮、输入框、菜单、卡片和列表都更紧凑，使 UI 能够承载更多内容而不会显得拥挤。 ## 为什么是全新样式？ (https://ui.shadcn.com/docs/changelog#why-a-new-style) 我们考虑过将 Luma 的间距调整一下，但 `--spacing` 是一个乘数。改变它会改变你应用中常用工具函数的意义。`p-2`、`w-4` 和 `m-16` 将不再表示相同的大小。 这种权衡感觉不对。紧凑不应该迫使你重新学习 Tailwind 的间距比例，或者怀疑一个工具函数在不同样式中是否意味着不同的东西。 因此，Rhea 成为一种新样式。它让我们可以直接调整组件大小、间隙和密度，同时保持底层工具函数比例的可预测性。 现已通过 shadcn/create (https://ui.shadcn.com/create) 提供，同时支持 Radix 和 Base UI。 尝试 Rhea (https://ui.shadcn.com/create?preset=b27GcrRo)