# 代理迁移指南 - 完整迁移 · HeroUI

> AI 助手的完整迁移指南，帮助将 HeroUI v2 迁移到 v3

- 页面: https://jiguang132.com/zh/systems/heroui/docs/migration/agent-guide-full
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## 概述

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


> 
  **关键约束**：HeroUI v2 和 v3 **不应在同一项目中共存**。该项目将在迁移过程中被破坏。始终在功能分支中工作并在切换依赖项之前迁移所有组件代码。


## 关键原则

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

## v3 的主要变化

<include>../index.mdx#major-changes</include>

## 详细迁移步骤

有关详细的分步说明，请参阅[完整迁移指南](/systems/heroui/docs/migration/full-migration)。该指南涵盖：

- 依赖项更新
- 主题配置更改
- 删除 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_guide`MCP 工具）
4. **参考指南**：使用`get_hooks_migration_guide`用于钩子迁移的 MCP 工具，`get_component_migration_guides`特定于组件的指南

## 组件导入更改

请参阅[完整迁移指南](/systems/heroui/docs/migration/full-migration#step-5-update-component-imports)了解详细的组件导入更改。

## 组件迁移参考

<include>../index.mdx#step-6-component-migration-reference</include>


> 
  **已删除/进行中/计划的组件**：对于标记为 ❌ 已删除、🔄 进行中或 📋 计划的组件，请在迁移过程中将其替换为标准 HTML 元素。一旦 HeroUI 组件在 v3 中可用，您就可以迁移回它们。


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

## v3 中的新组件

<include>../index.mdx#new-components-in-v3</include>

## 自定义主题覆盖

请参阅[完整迁移指南](/systems/heroui/docs/migration/full-migration#step-7-update-custom-theme-overrides)用于自定义主题覆盖迁移。

## 样式迁移

请参阅[完整迁移指南](/systems/heroui/docs/migration/full-migration#step-9-styling-migration)有关详细的样式迁移说明。

**代理注意**：使用`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-react`MCP 未连接（以避免混淆）
   - 验证 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_guide`MCP工具
   - 更新实用程序类、颜色标记、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. 将迁移分支合并回主分支

---


> 
  本代理迁移指南旨在与迁移 MCP 服务器配合使用。在开始迁移之前，请确保 MCP 服务器已正确配置并且工具可用。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt