在确定新项目技术栈时我最先想到的就是shadcn/ui因为它几乎与 Radix Primitives、Tailwind CSS 和可直接复制修改的组件代码成了固定搭配。

Radix 仍然存在但默认已改为 Base UI

2024 年 7 月，shadcn/ui 把 Base UI 设为新项目默认底层组件库。初始化命令生成的示例代码和文档都展示的是 Base UI，而不是过去熟悉的 Radix 版本。

痛点一：默认切换让人误以为 Radix 正在被弃用。怎么说呢，

如果你想继续使用 Radix。只需在初始化时指定：

pnpm dlx shadcn init -b radix

已有项目也不会被自动切换；shadcn 会按原来的底层实现生成代码。

说到官方强调，Radix 完全支持；现有项目无需迁移，shadcn 仍有基于 Radix 的生产项目，也没有计划全部改成 Base UI。

为什么 shadcn 更改默认值？

• 下载量与使用率：Base UI 已达到 5k+/周下载，shadcn/create 新项目选择比例约为 3:1。
• 功能覆盖：
  • Radix 的 Dialog、Popover、Dropdown Menu、Tooltip、Select 已成熟。怎么说呢，
  • Base UI 正快速补齐 Combobox、Autocomplete、Number Field、Drawer、OTP Field。还有更完整的 Field 与 Form。
• 痛点二：旧项目定制化高，迁移成本大。

定制化与迁移成本

A 项目通常会把组件源码放进 /components/ui;开发者常自行改样式、补属性或重构结构。 只因默认值变化就需要重新写大量代码，其收益远不及成本。例如打开设置 与 Base UI 的 `}>` 看似相似，却隐藏着不同的 API 与状态处理方式。

API 差异与实际影响

• `asChild` vs `render`：`asChild` 把触发行为交给子组件；`render` 则直接指定渲染元素，可用函数读取状态。
• `data-` vs `data-open`：`className="data-:animate-in"` 与 `className="data-open:animate-in"` 在写法上有细微差别，但对业务影响有限。但在自定义组件或复杂交互中，这些差异会导致类型报错或样式失效。说起来，
• Ai 开发混淆风险：Ai 在生成代码时可能混入两套 API。例如同时出现 `asChild data-` 与 `render={} data-open`，导致类型错误或行为不匹配。

如何在 PRD 和技术文档中明确底层实现？

UI 使用 shadcn/ui，底层采用 Base UI。不要生成 Radix 专用的 asChild、data-state 或 Radix CSS 变量。当前项目使用 shadcn/ui + Radix UI。保持现有 Radix API，不主动迁移到 Base UI。

我的最终选择策略

• 新项目：Straight to Base UI – 文档和 CLI 更顺手，功能覆盖更广。
• 旧项目：No migration unless necessary – 若能正常跑就不换底层，以避免不必要的重构成本。
• 技术栈说明："shadcn/ui" 或 "shadcn/ui" 明确写入，以防止 Ai 混用 API.

关注 shadcn/ui 本身而非单一底层库