代理迁移指南 - 共存增量迁移

概述

本指南专为人工智能助手（代理）设计，帮助用户使用增量共存迁移从 HeroUI v2 迁移到 v3。这种方法允许 v2 和 v3 组件并行工作，从而实现逐个组件迁移，同时保持项目正常运行。

关键原则

1. 增量组件迁移：一次迁移一个组件，在继续之前测试每个组件
2. 项目保持功能：与完全迁移不同，项目应始终保持工作状态
3. 策略识别：确定项目使用哪种共存策略（A：pnpm 别名或 B：组件包）
4. 逐个组件测试：在移动到下一个组件之前测试每个迁移的组件
5. CSS 冲突管理：监控并解决共存期间 v2 和 v3 之间的样式冲突
6. 已移除组件：没有 v3 对位的 v2 组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User）可在共存期间保留。除非用户明确要求替换，否则不要迁移它们。

v3 的主要变化

• 依赖项：将 React 升级到 v19+、HeroUI 包升级到 v3、Tailwind CSS 升级到 v4，并移除 Framer Motion
• 无需 Provider：v3 不再需要 HeroUIProvider
• 组件 API 更新：许多组件改用 React Aria Components 模式
• 复合组件：全新的复合组件模式带来了更好的定制能力。详情请参阅各组件的迁移指南。
• 已移除的 Hooks：v2 中的组件 Hooks（如 useSwitch、useInput）已被移除——请改用复合组件。useDisclosure 已被替换为 useOverlayState。详情请参阅 Hooks 迁移指南。
• 配置变更：从 Tailwind 配置中移除 heroui() 插件，更新 CSS 导入，并删除 hero.ts 文件
• 条目标识：集合类组件（Dropdown、ListBox、Select、Accordion 等）在 v3 中改用 id 和 textValue；列表本身仍需保留 React 的 key。

增量迁移设置

有关详细设置和迁移说明，请参阅增量迁移指南。该指南涵盖：

• 策略选择（A：pnpm 别名或 B：组件包）
• 每个策略的详细设置
• 共存的 CSS 配置
• 逐个组件的迁移过程
• CSS 冲突处理
• 完成迁移

策略识别

对于使用增量共存策略的项目，代理应该：

1. 确定策略：检查项目是否使用pnpm别名（策略A）或组件包（策略B）

   • 策略 A：寻找别名，例如"@heroui-v3/react": "npm:@heroui/react@latest"在 package.json 中
   • 策略 B：寻找特定于组件的包，例如@heroui/button, @heroui/card旁边@heroui/react

2. 验证设置：确保共存设置正确：

   • 策略A：两者兼而有之@heroui/react（v2）和@heroui-v3/react（v3 别名）已安装
   • 策略B：@heroui/react(v3) 和组件包，例如@heroui/button(v2) 已安装
   • CSS 已针对两个版本进行配置（请参阅 CSS 配置部分）

逐个组件的迁移指南

对于策略 A（pnpm 别名）：

1. 识别要迁移的组件

   • 查看组件迁移参考表
   • 使用get_component_migration_guides用于获取特定于组件的指南的 MCP 工具

2. 更新导入

   • 将导入从 @heroui/react 改为 @heroui-v3/react
   • 例子：import {Button} from "@heroui/react" → import {Button} from "@heroui-v3/react"

3. 更新组件代码

   • 遵循组件迁移指南get_component_migration_guides工具
   • 更新 props、组件结构和 API 调用
   • 如果需要，用复合组件替换挂钩

4. 测试迁移的组件

   • 验证组件正确渲染
   • 测试功能和交互
   • 检查样式冲突

5. 文档迁移

   • 跟踪哪些组件已迁移
   • 注意任何问题或疑虑

对于策略 B（组件包）：

1. 识别要迁移的组件

   • 查看组件迁移参考表
   • 使用get_component_migration_guides用于获取特定于组件的指南的 MCP 工具

2. 移除组件包

   • 从依赖项中删除 v2 组件包（例如，@heroui/button)
   • 更新package.json

3. 更新导入

   • 将组件包中的导入更改为@heroui/react(v3)
   • 例子：import {Card} from "@heroui/card" → import {Card} from "@heroui/react"

4. 更新组件代码

   • 遵循组件迁移指南get_component_migration_guides工具
   • 更新 props、组件结构和 API 调用
   • 如果需要，用复合组件替换挂钩

5. 测试迁移的组件

   • 验证组件正确渲染
   • 测试功能和交互
   • 检查样式冲突

6. 文档迁移

   • 跟踪哪些组件已迁移
   • 注意任何问题或疑虑

处理移除的组件（无 v3 对应项）

当遇到没有 v3 对位的 v2 组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User）时：

• 将它们留在原处 - 不要尝试迁移它们，除非用户明确请求删除
• 如果用户想要删除它们：使用get_component_migration_guides（如果有）或组件迁移参考获取指南并帮助替换为原生 HTML 或手动实现

CSS 冲突处理

共存期间，v2 和 v3 CSS 系统都会被加载。代理应该：

1. 监控冲突

   • 注意样式不一致
   • 检查v2和v3样式是否冲突
   • 验证两个 CSS 导入均存在且顺序正确

2. 指导冲突解决

   • 确保 CSS 导入顺序：tailwindcss首先，然后@heroui/styles
   • 检查 Tailwind 配置是否配置了 v2 插件
   • 验证 v3 CSS 是否正确导入

3. 每次迁移后测试样式

   • 验证迁移的组件看起来正确
   • 检查是否有意外的样式覆盖
   • 确保 v2 组件的样式仍然正确

组件迁移参考

可以通过下表快速查找每个组件的迁移指南。点击「迁移指南」列中的链接，即可跳转到对应的详细迁移说明。

使用get_component_migration_guidesMCP 工具可获取每个组件的详细指南。

v3 中的新组件

v3 引入了一系列 v2 中尚未提供的全新组件：

完成步骤

迁移所有组件后：

1. 删除 v2 依赖项

   • 策略A：删除@heroui/react, @heroui/theme和别名
   • 策略B：删除所有剩余的@heroui/*组件包
   • 如果项目仍包含上述已移除 v2 组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User），请告知用户：他们可稍后在代理协助下按指南移除或替换。

2. 更新所有导入

   • 策略A：改变@heroui-v3/react → @heroui/react
   • 策略 B：所有导入应已指向 @heroui/react（v3）

3. 更新CSS配置

   • 从配置中删除 v2 Tailwind 插件
   • 仅保留@import "@heroui/styles";
   • 删除 v2 CSS 导入

4. 完成样式迁移

   • 遵循样式迁移指南
   • 使用get_styling_migration_guideMCP工具
   • 更新实用程序类、颜色标记等。

与完全迁移的差异

主要区别：

• 项目状态：项目在迁移过程中保持功能（无损坏状态）
• 迁移速度：可以在较长时间内逐个组件进行迁移
• 测试：可以在完全迁移之前测试 v3 组件和 v2 组件
• 分支策略：功能分支不太重要（尽管仍然推荐）
• 依赖管理：两个版本暂时共存
• CSS 处理：两个 CSS 系统在共存期间加载

何时使用增量共存：

• 需要逐步迁移的大型代码库
• 迁移期间必须保持功能的项目
• 想要增量测试 v3 组件的团队
• 已使用特定于组件的包的项目（策略 B）

何时使用完全迁移：

• 可以快速迁移的较小项目
• 可以接受临时破坏状态的项目
• 喜欢一次性迁移的团队
• 项目使用统一@heroui/react包（策略 A 可以工作，但完全迁移可能更简单）

代理最佳实践

1. 验证项目仍然正常运行

   • 每个组件迁移后，确保项目仍然有效
   • 测试已迁移和未迁移的组件
   • 立即报告任何问题

2. 指导逐个组件迁移

   • 帮助一次迁移一个组件
   • 使用get_component_migration_guides适用于每个组件的 MCP 工具
   • 在继续之前彻底测试

3. 监控 CSS 冲突

   • 注意 v2 和 v3 之间的样式问题
   • 指导解决冲突
   • 确保 CSS 配置正确

4. 跟踪迁移进度

   • 保留已迁移组件的清单
   • 记录任何问题或疑虑
   • 注意正在使用哪种策略

5. 指导完成步骤

   • 迁移所有组件后，指导删除 v2 依赖项
   • 帮助将所有导入更新为仅限 v3
   • 指导样式迁移完成

常见场景

大型项目（100 多个组件）

• 随着时间的推移逐步迁移组件
• 彻底测试每个组件
• 监控 CSS 冲突
• 可能需要数周或数月才能完成

小型项目（<20 个组件）

• 可以更快地迁移
• 仍然测试每个组件
• 减少 CSS 冲突风险
• 可能在几天内完成

混合战略项目

• 有些项目可能对某些组件使用策略 A，对其他组件使用策略 B
• 指导每个组件进行适当的导入更新
• 尽可能确保方法一致

项目使用 v2 导航栏（或其他已删除的组件）

• 留在原处 —— v2 Navbar 与其他已移除组件（Code、Image、Ripple、Snippet、Spacer、User）在共存期间仍会继续工作
• 告知用户：若不再需要，可在代理协助下移除；替换方案见 组件迁移参考。

下一步

完成迁移后：

1. 删除 v2 依赖项（已在完成步骤中完成）
2. 从迁移 MCP 切换到用于 v3 开发的 heroui-react MCP
3. 更新文档中的引用
4. 运行最终验证
5. 完成样式迁移

---