HeroUI v2 到 v3 全量迁移如何更新依赖并在迁移期间用 typecheck 代替 build 验证【免费下载链接】nextui Beautiful, fast and modern React UI library. (Previously NextUI)项目地址: https://gitcode.com/GitHub_Trending/ne/nextui这篇文章处理一个具体的任务把使用 HeroUI v2 的 React 项目按官方推荐的全量迁移Full Migration方式切换到 v3重点解决两件事——依赖按什么顺序、用什么命令更新以及在迁移过程中项目处于不可构建状态时用什么手段检查代码错误。前提是你有一个 HeroUI v2 项目准备升级到 v3v3 要求 React 19 和 Tailwind CSS v4。先明确迁移规则v2 和 v3 不能共存全量迁移的核心约束来自官方文档 Full Migration/full-migration.mdx)迁移期间项目是坏的brokenv2 和 v3 无法共存因此要在功能分支feature branch上工作保持主分支可用迁移分两个阶段准备阶段仍在 v2 依赖上迁移所有组件代码代码会处于破坏状态和切换阶段把依赖更新到 v3修复剩余问题。这个规则直接决定了依赖更新的顺序React、Tailwind 这些依赖可以提前升但 HeroUI 包本身的切换必须等所有组件代码迁移完成后才能做。迁移期间的验证规则typecheck 和 lint不是 build文档在迁移流程中给出了一条关键禁令——不要用 build 来检查迁移过程中的错误使用typecheck例如tsc --noEmit检查 TypeScript 错误如果项目可用使用lint例如eslint、biome check检查代码质量如果可用不要运行构建命令例如npm run build、next build、vite build不要在迁移期间尝试启动/运行项目。原因和上面第一条规则一致全量迁移期间项目本来就构建不过、跑不起来。如果拿 build 的失败当迁移进度的判断依据你会被预期的报错淹没。迁移过程中每一步修改之后用下面这两条命令定位实际问题# 检查 TypeScript 错误 tsc --noEmit # 检查代码质量任选你项目里实际使用的一个 npx eslint . npx biome check .其中tsc --noEmit、eslint、biome check是文档给出的示例命令前提是你的项目里确实配置了 TypeScript 或对应的 lint 工具文档原文的表述是 if available。依赖更新步骤一先升 React 到 19v3 要求 React 19。这一步可以在切换 HeroUI 包之前完成文档明确说明这样做不会破坏项目所以建议先做让后续 typecheck 报出的类型错误都基于 React 19 的类型。按你使用的包管理器执行# npm npm install react^19.0.0 react-dom^19.0.0 # pnpm pnpm add react^19.0.0 react-dom^19.0.0 # yarn yarn add react^19.0.0 react-dom^19.0.0 # bun bun add react^19.0.0 react-dom^19.0.0升完之后跑一次tsc --noEmit把 React 19 引入的类型错误比如 ref 相关类型的变化先消化掉避免它们和 HeroUI v3 的类型错误混在一起。依赖更新步骤二先迁完组件代码再切换 HeroUI 包文档对切换 HeroUI 包有一条硬性顺序要求必须在所有组件代码迁移完成之后执行。也就是说切换包之前你需要按 Full Migration 指南/full-migration.mdx) 的步骤 3 到 6 完成这些代码迁移这些步骤在 v2 依赖尚存的项目上进行移除应用根部的HeroUIProviderv3 不再需要 Provider把所有组件导入统一收敛到heroui/react单一包处理被移除的 hooksuseSwitch、useInput等改为复合组件useDisclosure换成useOverlayState参见 Hooks 迁移指南按各组件的迁移指南处理 API、props 和结构变化组件对照表见 迁移总览 的 Component Migration Reference 章节。完成以上代码迁移后才执行依赖切换卸载 v2 包安装 v3 包。# npm npm uninstall heroui/react heroui/theme npm install heroui/styles heroui/react # pnpm pnpm remove heroui/react heroui/theme pnpm add heroui/styles heroui/react # yarn yarn remove heroui/react heroui/theme yarn add heroui/styles heroui/react # bun bun remove heroui/react heroui/theme bun add heroui/styles heroui/react依赖更新步骤三移除 Framer Motion升级 Tailwind CSS 到 v4v3 不再依赖 Framer Motion动画改为基于 CSS 实现所以要卸载它# npm npm uninstall framer-motion # pnpm pnpm remove framer-motion # yarn yarn remove framer-motion # bun bun remove framer-motion然后把 Tailwind CSS 升到 v4# npm npm install tailwindcss^4.0.0 # pnpm pnpm add tailwindcss^4.0.0 # yarn yarn add tailwindcss^4.0.0 # bun bun add tailwindcss^4.0.0随依赖切换必须改的配置依赖换完后文档的 Step 2Update Theming Configuration要求同步修改两处配置否则 typecheck 和后续构建都会持续报错1. 移除 Tailwind 插件配置。v2 的tailwind.config.js里有heroui()插件// v2 的 tailwind.config.js迁移前 const {heroui} require(heroui/react); module.exports { content: [ ./src/**/*.{js,ts,jsx,tsx}, ./node_modules/heroui/theme/dist/**/*.{js,ts,jsx,tsx}, ], plugins: [heroui()], };v3 的做法是删掉heroui()插件。如果你没有别的自定义可以直接删掉整个tailwind.config.js否则保留文件、只删掉 HeroUI 插件部分。2. 更新全局 CSS 导入并注意顺序。/* v2 */ tailwind base; tailwind components; tailwind utilities; /* v3 */ import tailwindcss; import heroui/styles;文档特别强调导入顺序必须先导入tailwindcss再导入heroui/styles。另外如果你为 v2 创建过hero.ts主题文件v3 不需要它可以删除rm hero.ts这一步会删除你本地的hero.ts文件执行前确认该文件确实是你为 v2 主题创建的。验证迁移结果按上面的规则验证分两个层面迁移过程中代码坏掉的阶段每次修改后运行tsc --noEmit和 lint以工具报出的错误清单作为定位依据对照各组件、hooks、styling 的迁移指南逐个修复。这个阶段 build 失败、项目跑不起来都是预期状态不是需要修好的问题。全部迁移完成后组件、hooks、样式迁移都做完了文档的 Step 10 要求在测试层面做五类检查——视觉所有组件渲染正确、功能交互行为、无障碍键盘导航与屏幕阅读器、响应式不同屏幕尺寸、性能bundle size 与运行时表现。到这里才可以重新运行项目做人工验证因为代码已经对齐 v3build 不再是预期失败的状态。限制与替代路径全量迁移期间主分支保持可用、功能分支处于坏状态这是该方式的固有代价不是操作失误如果你无法接受迁移期间项目不可用例如团队要持续发布文档提供了另一条路径Incremental Migration/incremental-migration.mdx)通过 pnpm aliases 或组件包让 v2/v3 共存、逐组件迁移代价是初始配置更复杂、可能遇到样式冲突如果需要 AI 辅助完成迁移文档提供了三个入口Migration MCP Server、Migration Agent Skills、AGENTS.md把迁移文档下载到项目里离线使用见 迁移总览 的对照表。完成依赖切换和代码修复后下一步就是按 Full Migration 指南/full-migration.mdx) 的 Next Steps 对照 v3 组件文档核对 API并在功能分支合并前跑完 Step 10 的五类测试。【免费下载链接】nextui Beautiful, fast and modern React UI library. (Previously NextUI)项目地址: https://gitcode.com/GitHub_Trending/ne/nextui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考