# 代理迁移指南 - 共存增量迁移 · HeroUI

> AI 助手增量共存迁移指南，帮助将 HeroUI v2 迁移到 v3

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

## 概述

本指南专为人工智能助手（代理）设计，帮助用户使用**增量共存迁移**从 HeroUI v2 迁移到 v3。这种方法允许 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 的主要变化

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

## 增量迁移设置

有关详细设置和迁移说明，请参阅[增量迁移指南](/systems/heroui/docs/migration/incremental-migration)。该指南涵盖：

- 策略选择（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`（如果有）或[组件迁移参考](/systems/heroui/docs/migration#component-migration-reference)获取指南并帮助替换为原生 HTML 或手动实现

## CSS 冲突处理

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

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

2. **指导冲突解决**
   - 确保 CSS 导入顺序：`tailwindcss`首先，然后`@heroui/styles`
   - 检查 Tailwind 配置是否配置了 v2 插件
   - 验证 v3 CSS 是否正确导入

3. **每次迁移后测试样式**
   - 验证迁移的组件看起来正确
   - 检查是否有意外的样式覆盖
   - 确保 v2 组件的样式仍然正确

## 组件迁移参考

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

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

## v3 中的新组件

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

## 完成步骤

迁移所有组件后：

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_guide`MCP工具
   - 更新实用程序类、颜色标记等。

## 与完全迁移的差异

**主要区别：**

- **项目状态**：项目在迁移过程中保持功能（无损坏状态）
- **迁移速度**：可以在较长时间内逐个组件进行迁移
- **测试**：可以在完全迁移之前测试 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**）在共存期间仍会继续工作
- 告知用户：若不再需要，可在代理协助下移除；替换方案见 [组件迁移参考](/systems/heroui/docs/migration#component-migration-reference)。

## 下一步

完成迁移后：

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

---


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

---

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