{
  "dependencies": {
    "@heroui/react": "2.8.6",
    "@heroui/theme": "2.4.24",
    "@heroui-v3/react": "npm:@heroui/react@latest",
    "@heroui-v3/styles": "npm:@heroui/styles@latest"
  }
}

从以下位置导入 v2 组件@heroui/react:

import {Button} from "@heroui/react"; // v2

从以下位置导入 v3 组件@heroui-v3/react:

import {Button} from "@heroui-v3/react"; // v3

迁移过程

一次迁移一个组件：
- 更新导入以使用@heroui-v3/react
- 将组件代码更新为 v3 API
- 测试迁移的组件
- 验证样式看起来正确
- 对于没有 v3 对位的 v2 组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User），请将它们保留在原处，它们在共存期间仍会继续工作。
继续，直到所有组件均已迁移
- 跟踪哪些组件已迁移
- 彻底测试每个迁移的组件
- 如果您想稍后删除 v2 删除的组件，请使用组件迁移参考指南并要求您的代理帮助将其替换为原生 HTML 或手动实施。
迁移所有组件后，切换到仅 v3：
- 删除 v2 依赖项（@heroui/react, @heroui/theme)
- 删除别名
- 将所有导入更新为@heroui/react（消除-v3后缀）
- 完成样式迁移

注意事项

两个 CSS 系统都将被加载（v2 通过 Tailwind 插件，v3 通过 CSS 导入）
您暂时需要两个 Tailwind 配置
迁移过程中捆绑包大小会变大
可能会发生一些样式冲突

策略 B：使用组件包

该策略将 v2 的特定于组件的包与 v3 的统一包一起使用。

设置

安装v3主包和v2组件包：

{
  "dependencies": {
    "@heroui/react": "latest", // v3
    "@heroui/styles": "latest", // v3
    "@heroui/button": "2.8.6", // v2
    "@heroui/card": "2.8.6", // v2
    // ... other v2 component packages as needed
  }
}

从以下位置导入 v3 组件@heroui/react:

import {Button} from "@heroui/react"; // v3

从组件包中导入 v2 组件：

import {Card} from "@heroui/card"; // v2

迁移过程

安装 v3 软件包 (@heroui/react, @heroui/styles)
为尚未迁移的组件安装 v2 组件包
一次迁移一个组件：
- 从依赖中删除 v2 组件包
- 更新导入以使用@heroui/react(v3)
- 将组件代码更新为 v3 API
- 测试迁移的组件
- 对于没有 v3 对位的 v2 组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User），请将它们保留在原处，它们在共存期间仍会继续工作。
继续，直到所有组件均已迁移
- 如果您想稍后删除 v2 删除的组件，请使用组件迁移参考指南并要求您的代理帮助将其替换为原生 HTML 或手动实施。
删除剩余的 v2 组件包
完成样式迁移

注意事项

仅当您的项目使用特定于组件的包时才有效
需要管理多个包依赖关系
v3 没有组件包，因此这是一种单向迁移路径

共存的 CSS 配置

在共存期间，您将需要两个 CSS 系统：

/* globals.css */
@import "tailwindcss";

/* v2 styles via Tailwind plugin */
/* (configured in tailwind.config.js) */

/* v3 styles */
@import "@heroui/styles";

重要提示： 导入顺序很重要：先导入 tailwindcss，再导入 @heroui/styles。

Tailwind配置

您暂时需要两个 Tailwind 配置：

v2 配置（tailwind.config.js）：

const {heroui} = require("@heroui/react");

module.exports = {
  plugins: [heroui()],
  // ... other config
};

v3 配置： 不需要插件，但确保安装 Tailwind v4。

组件迁移

对于您迁移的每个组件：

查看组件迁移指南
- 使用组件迁移参考表
- 检查特定于组件的迁移指南
更新导入
- 策略A：改变@heroui/react → @heroui-v3/react
- 策略 B：更改组件包 →@heroui/react
更新组件代码
- 遵循组件迁移指南
- 更新 props、组件结构和 API 调用
- 如果需要，用复合组件替换挂钩
测试迁移的组件
- 验证组件正确渲染
- 测试功能和交互
- 检查样式冲突
- 确保 v2 组件的样式仍然正确
文档迁移
- 跟踪哪些组件已迁移
- 注意任何问题或疑虑

CSS 冲突处理

共存期间，v2 和 v3 CSS 系统都会被加载。监控冲突：

注意样式不一致
- 检查v2和v3样式是否冲突
- 验证两个 CSS 导入均存在且顺序正确
指导冲突解决
- 确保 CSS 导入顺序：tailwindcss首先，然后@heroui/styles
- 检查 Tailwind 配置是否配置了 v2 插件
- 验证 v3 CSS 是否正确导入
每次迁移后测试样式
- 验证迁移的组件看起来正确
- 检查是否有意外的样式覆盖
- 确保 v2 组件的样式仍然正确

完成迁移

迁移所有组件后：

删除 v2 依赖项：
- 消除@heroui/react和@heroui/theme（策略A）
- 全部删除@heroui/*组件包（策略B）
- 删除别名（策略 A）
- 如果你将已移除的 v2 组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User）保留在项目中，有两个选择：(1) 在删除 v2 依赖前按迁移指南替换它们，或 (2) 暂时保留 v2 依赖，直到你准备好替换。你也可以请代理依据指南协助移除或替换。
更新所有导入：
- 改变@heroui-v3/react → @heroui/react（策略A）
- 更改组件包导入 →@heroui/react（策略B）
更新CSS：
- 从配置中删除 v2 Tailwind 插件
- 仅保留@import "@heroui/styles";
完成样式迁移：
- 遵循样式迁移指南
- 更新实用程序类、颜色标记等。

共存迁移清单

使用此清单来跟踪增量迁移进度：

初始设置

选择策略（A：别名或B：组件包）
安装 v3 软件包（使用别名或直接安装）
为两个版本配置 CSS
确保已安装 React 19+
临时设置两个 Tailwind 配置

组件迁移（对每个组件重复）

查看组件迁移指南
更新导入（策略 A 或 B）
将组件代码更新为 v3 API
测试迁移的组件
检查样式冲突
记录迁移进度
识别已移除的 v2 组件（Code、Image、Navbar、Ripple、Snippet、Spacer、User）——保留在原处或按指南替换

完成

迁移所有组件
可选：在删除 v2 deps 之前使用迁移指南替换已删除的组件，或者仅在替换所有已删除的组件后删除 v2 deps
删除 v2 依赖项
删除别名（策略 A）
将所有导入更新为仅限 v3
删除 v2 Tailwind 插件
将 CSS 更新为仅限 v3
完成样式迁移
测试整个应用程序

下一步

完成增量迁移后：

回顾v3 组件文档
探索 v3 中可用的新组件
查看样式指南
了解构图模式

增量迁移

本页目录