shadcn-migration

一份针对 shadcn/ui 的 Radix UI 与 Base UI 基元之间的逐步迁移指南（第三种基元 React Aria 没有文档化的迁移路径），以及 CLI 迁移（`migrate radix|cn|rtl|icons|base-color`）：迁移前检查清单（检测、备份分支、组件清单）、迁移顺序（先迁移叶子组件——Tooltip/Switch/Checkbox，再迁移 Accordion/Tabs，最后迁移 Dialog/Select/Popover/Menu）、API 转换表（`asChild`→`render`、`DialogContent`→`Dialog.Popup`、`data-state`→`data-[open]` 等），以及迁移后的验证清单。

shadcn 迁移

Agent 工作流（强制）

迁移前，并行启动以下 Agent，每个名称各调用一次 Agent：

1. fuse-ai-pilot:explore-codebase - 清点所有受影响的组件
2. fuse-ai-pilot:research-expert - 通过 Context7 验证迁移模式

迁移后：运行 fuse-ai-pilot:sniper 进行验证。

---

概览

功能	说明
Radix -> Base UI	可选：自 2026 年 7 月起，Base UI 是新项目的默认选项；Radix 并未弃用
Base UI -> Radix	迁移到 Radix 基元（仍受全面支持）
React Aria	第三种基元（aria-*，2026 年 7 月）；没有往返迁移的文档化路径；“现有项目继续使用当前基元”
API 映射	完整转换表
验证	迁移后检查清单

官方迁移工具

需求	命令 / 工具	来源
Radix -> Base UI，按组件迁移	npx skills add shadcn/ui，然后让 Agent 执行“migrate accordion to base-ui”（渐进式迁移，每个组件单独提交，并在 .migration/<component>.md 中报告）	changelog 2026-07-base-ui-default
@radix-ui/react-* -> 统一的 radix-ui	{runner} shadcn@latest migrate radix [path]	/docs/cli#migrate-radix
clsx + tailwind-merge -> cn 包	{runner} shadcn@latest migrate cn [path]（合并引擎面向 Tailwind v4，与 tailwind-merge v3 一致；使用 Tailwind v3 时保留 tailwind-merge v2，仅迁移 clsx 是安全的；不需要 components.json）	/docs/cli#migrate-cn
物理类名 -> 逻辑类名（RTL）	{runner} shadcn@latest migrate rtl [path]	/docs/cli#migrate-rtl
切换图标库	{runner} shadcn@latest migrate icons --from lucide --to phosphor	/docs/cli#migrate-icons
切换基础颜色	{runner} shadcn@latest migrate base-color --to zinc	/docs/cli#migrate-base-color
在非交互式 CI 初始化中保留 Radix	{runner} shadcn@latest init -b radix（默认基元现为 base）	changelog 2026-07-base-ui-default

{runner} shadcn@latest migrate --list 会列出可用的迁移（CLI 4.21.0：cn、icons、base-color、radix、rtl）。

关键规则

1. 始终先运行检测，再开始迁移
2. 迁移前始终创建备份分支
3. 一次只迁移一种组件
4. JSX 更改时，同时更新 CSS 选择器
5. 每迁移完一个组件，都要运行测试

架构

Migration order (leaf components first):
1. Tooltip, Switch, Checkbox (simple)
2. Accordion, Tabs (medium)
3. Dialog, Select, Popover, Menu (complex)

-> 请参阅 migration-dialog.md 查看完整示例

---

迁移前检查清单

[ ] Run shadcn-detection to confirm current primitive
[ ] Create backup branch (git checkout -b pre-migration)
[ ] Inventory all affected files (Grep for imports)
[ ] Review component-specific API changes
[ ] Plan migration order (leaf components first)

---

迁移工作流

1. DETECT  -> Run shadcn-detection skill
2. BACKUP  -> Create git branch
3. INVENTORY -> List all affected components
4. TRANSFORM -> Apply API changes per component
5. VALIDATE -> Run tests + sniper check

---

主要 API 变更

方面	Radix	Base UI
组合方式	asChild	render prop
Dialog 内容（原语）	Dialog.Content	Dialog.Popup（shadcn 封装保留 DialogContent）
Dialog 遮罩层（原语）	Dialog.Overlay	Dialog.Backdrop（封装保留 DialogOverlay）
定位	内置	独立的 Positioner
Accordion 主体（原语）	Accordion.Content	Accordion.Panel（封装保留 AccordionContent）
Accordion 单项/多项	type="single" collapsible / type="multiple"	defaultValue={[...]} / multiple
原始数据属性	data-state="open"	data-open（Tailwind data-open: 变体可匹配两者）
包	radix-ui（或旧版 @radix-ui/react-*）	单一的 @base-ui/react
components.json 样式	radix-*（旧版 new-york）	base-*

---

最佳实践

应该做

• 每次迁移一种组件类型
• 每迁移一种组件后运行测试
• 同步更新 CSS 选择器和 JSX
• 迁移后移除未使用的 Radix 包

不应该做

• 一次性迁移所有组件
• 跳过检测步骤
• 在生产环境中混用 API
• 忘记更新数据属性 CSS 选择器

参考指南

概念

主题	参考资料	何时查阅
Radix -> Base UI	radix-to-baseui.md	从 Radix 迁移
Base UI -> Radix	baseui-to-radix.md	迁移到 Radix

模板

模板	使用时机
migration-dialog.md	完整迁移示例