代理迁移指南 - 完整迁移

概述

本指南专为人工智能助手（代理）设计，帮助用户从 HeroUI v2 迁移到 v3。它实现了完整迁移方法，首先分析项目并以可管理的批次迁移组件，而不是一次性迁移全部组件。

关键原则

1. 完整迁移：不要试图在一次改动中迁移所有组件；应按可管理的批次推进。大型项目同样需要采用完整迁移流程（在切换依赖前完成全部组件适配）。
2. 首先进行项目分析：在创建迁移计划之前，始终分析代码库以了解组件的使用情况。
3. 损坏的状态管理： 严重：项目将在迁移过程中损坏。为此制定计划：
   • 在功能分支中迁移
   • 在切换依赖项之前准备好所有代码更改
   • 制定回滚计划
   • 首先在隔离环境中进行测试
4. 全有或全无依赖关系切换：依赖关系更新到 v3 后，必须迁移所有组件。在切换依赖关系之前规划组件迁移。

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。

详细迁移步骤

有关详细的分步说明，请参阅完整迁移指南。该指南涵盖：

• 依赖项更新
• 主题配置更改
• 删除 HeroUIProvider
• 组件导入和迁移
• 钩子迁移
• 样式迁移
• 测试

代理注意：依赖项更新（React 19、Tailwind v4）可以在切换 HeroUI 之前完成（不会破坏项目）。但是，HeroUI 包切换只能在所有组件代码迁移之后进行。

钩子迁移

HeroUI v2 提供了组件挂钩（例如useSwitch, useInput, useCheckbox等）和实用程序挂钩，例如useDisclosure。 HeroUI v3 删除了大多数组件挂钩，转而使用复合组件，并替换了useDisclosure和useOverlayState.

何时迁移钩子：

• 组件迁移期间：替换组件钩子（useSwitch, useInput等）当您迁移每个组件以使用复合组件时
• 组件迁移后：迁移useDisclosure → useOverlayState用于样式迁移之前的覆盖状态管理

迁移策略：

1. 识别钩子用法：搜索代码库以从以下位置导入@heroui/react包括钩子名称（useSwitch, useInput, useCheckbox, useRadio, useDisclosure， ETC。）
2. 替换组件钩子：使用复合组件而不是带有 prop getter 的钩子（在组件迁移期间完成）
3. 替换 useDisclosure：迁移到useOverlayState用于覆盖状态管理（使用get_hooks_migration_guideMCP 工具）
4. 参考指南：使用get_hooks_migration_guide用于钩子迁移的 MCP 工具，get_component_migration_guides特定于组件的指南

组件导入更改

请参阅完整迁移指南了解详细的组件导入更改。

组件迁移参考

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

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

v3 中的新组件

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

自定义主题覆盖

请参阅完整迁移指南用于自定义主题覆盖迁移。

样式迁移

请参阅完整迁移指南有关详细的样式迁移说明。

代理注意：使用get_styling_migration_guide用于全面样式迁移详细信息的 MCP 工具。

重要：样式迁移发生在组件迁移和依赖关系切换之后。

完整的迁移工作流程

重要：由于 v2 和 v3 无法共存，因此迁移分两个主要阶段进行：

1. 准备阶段：迁移所有组件代码，同时仍依赖 v2 依赖项（代码将被破坏）
2. 切换阶段：将依赖项更新到 v3 并修复任何剩余问题

⚠️ 关键：不要构建来检查迁移过程中的错误

• 使用类型检查（例如，tsc --noEmit) 如果可以检查 TypeScript 错误
• 使用lint（例如，eslint, biome check) 如果可以检查代码质量
• 不要运行构建命令（例如，npm run build, next build, vite build)
• 请勿 在迁移期间尝试启动/运行项目

第 0 阶段：设置和分析

1. 创建迁移分支

   • 创建一个功能分支用于迁移工作
   • 例子：git checkout -b migrate/heroui-v3

2. 验证迁移 MCP 是否已配置

   • 检查迁移 MCP 服务器是否已连接
   • 确保heroui-reactMCP 未连接（以避免混淆）
   • 验证 MCP 工具可用

3. 分析项目并创建迁移计划

   • 使用get_migration_workflow获取本指南
   • 扫描 HeroUI v2 导入，识别所有组件和使用情况
   • 映射组件依赖关系
   • 创建分阶段迁移计划（例如，每个阶段 3-5 个组件，按依赖项策略）

第 1 阶段：依赖项准备（代码更改之前）

这些步骤可以在切换 HeroUI 依赖项之前完成，并且不会破坏项目：

1. 将 React 更新到 v19（如果还没有）

   • 这可以在切换 HeroUI 之前完成

2. 将 Tailwind CSS 更新至 v4（如果尚未更新）

   • 这可以在切换 HeroUI 之前完成

3. 🛑 检查点：停止并等待用户批准

   • 不要自动进入下一阶段
   • 解释配置更改
   • 在继续之前等待明确的用户批准

第 2-N 阶段：代码迁移（v2 依赖项仍然有效）

关键：在此阶段，代码将引用 v3 API，但仍安装 v2 依赖项。该项目将被破坏。这是预期的且正常的。

对于迁移计划中的每个组件组：

1. 获取特定于组件的指南

   • 使用get_component_migration_guides适用于每个组件的 MCP 工具
   • 审查 API 更改、prop 迁移、结构更改

2. 应用代码迁移

   • 将组件代码迁移到 v3 API 模式
   • 更新导入、道具、组件结构
   • 注意：在切换依赖关系之前，代码将被破坏

3. 处理依赖关系

   • 如果组件有依赖，先迁移依赖
   • 检查依赖项是否已经迁移
   • 根据需要迁移共享代码

4. 🛑 检查点：停止并等待用户批准

   • 不要自动进入下一阶段
   • 总结一下本阶段迁移的内容
   • 在继续之前等待明确的用户批准

5. 记录迁移状态

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

最终阶段：依赖关系切换和修复

关键：仅当所有组件都已迁移到 v3 API 模式时才继续。

1. 更新依赖关系

   • 消除@heroui/react和@heroui/theme（v2）
   • 安装@heroui/react和@heroui/styles(v3)
   • 消除framer-motion如果存在
   • 更新 CSS 导入（添加@import "@heroui/styles";)
   • 从应用程序根目录中删除 HeroUIProvider
   • 更新 Tailwind 配置（删除heroui()插件）

2. 修复剩余问题

   • 运行 typecheck/lint（如果可用）（不构建）
   • 修复类型检查报告的任何 TypeScript 错误
   • 修复任何 linting 错误
   • 注意：请勿在迁移期间尝试构建或运行项目

3. 🛑 检查点：停止并等待用户批准

   • 不要自动进行样式设置
   • 验证组件是否正常工作
   • 在样式迁移之前等待明确的用户批准

4. 继续样式迁移

   • 使用 get_styling_migration_guide MCP 工具获取样式迁移指南
   • 系统地应用样式更新

5. 应用样式更新

   • 使用get_styling_migration_guideMCP工具
   • 更新实用程序类、颜色标记、CSS 变量
   • 测试视觉外观

6. 最终验证

   • 最后运行一次类型检查/lint（不构建）
   • 验证所有样式是否正确更新
   • 注意：完整测试（视觉、功能、可访问性）应在迁移完成后完成，而不是在迁移期间完成

迁移策略

策略 1：按依赖关系（推荐）

• 首先迁移基础组件（按钮、输入、卡等）
• 然后迁移依赖它们的组件
• 最适合具有复杂组件层次结构的项目
• 确保依赖项先于依赖项准备就绪

订单示例：

1. 按钮、输入、链接（基础）
2. 卡片、模态（使用按钮）
3. 表单、下拉菜单（使用输入、按钮）
4. 复杂组件（使用多个依赖项）

策略 2：按功能

• 将功能/模块中的所有组件迁移到一起
• 适合基于功能的代码组织
• 允许逐个功能测试
• 可能需要先迁移依赖项

例子：

• 功能：用户身份验证
  • 迁移：输入、按钮、表单、模态（所有与身份验证相关）
• 功能：仪表板
  • 迁移：卡、选项卡、选择（所有与仪表板相关）

策略 3：按频率

• 首先迁移最常用的组件
• 提供快速获胜和早期验证
• 适合具有清晰使用模式的大型代码库
• 仍然需要处理依赖关系

例子：

1. 按钮（使用150次）
2. 输入（使用120次）
3. 卡（已使用80次）
4. ...（按使用次数继续）

代理最佳实践

1. 关于损坏状态的警告

   • 始终通知用户项目在迁移过程中将被破坏
   • 推荐使用功能分支
   • 设定项目何时再次运作的预期

2. 切换依赖项之前迁移所有代码

   • 首先完成所有组件代码迁移
   • 仅当迁移所有组件时才切换依赖项
   • 这最大限度地减少了破坏状态的持续时间

3. 每个阶段使用 MCP 工具

   • 使用get_migration_workflow, get_component_migration_guides, get_styling_migration_guide根据需要
   • 关键：始终在检查点停止并等待阶段之间的用户批准

4. 在功能分支工作

   • 始终建议创建迁移分支
   • 允许用户继续在主分支上工作
   • 如果需要，启用轻松回滚

5. 记录迁移状态

   • 跟踪哪些组件已迁移
   • 注意任何问题或疑虑
   • 保持清单可见
   • 每个阶段后更新状态

6. 优雅地处理错误

   • 如果组件迁移失败，请记录原因
   • 继续其他组件
   • 依赖切换后返回失败的组件
   • 更新依赖项后，某些问题可能会得到解决

7. 依赖关系切换后验证

   • 仅在依赖项更新到 v3 后
   • 运行类型检查/lint（不构建）
   • 修复出现的类型/lint 错误
   • 在类型检查/lint 通过之前不要继续进行样式设置

常见场景

大型项目（100 多个组件）

• 使用较小的批量（3-5 个组件）
• 按依赖性或频率确定优先级
• 允许多个会话
• 在阶段之间创建检查点
• 使用“按依赖”策略
• 清楚地记录进度

小型项目（<20 个组件）

• 可以使用更大的批次（5-10 个组件）
• 可以通过更少的阶段完成
• 仍然增量验证（全迁移方式）
• 可以使用任何策略
• 在切换 deps 之前仍然需要迁移所有代码

混合 v2/v3 使用（完全迁移）

• 完全迁移中不可能：v2 和 v3 不能在完全迁移方法中共存
• 在切换依赖关系之前必须迁移所有组件
• 使用功能分支来维护工作主分支
• 一次性完成迁移

下一步

完成迁移后：

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

---