HeroUI v3：从 NextUI 到 Tailwind CSS v4 时代的 React 组件库重写

预计阅读时间：9 分钟

HeroUI v3 不是一次普通改名。这个原名 NextUI 的 React 组件库，在 v3 中做了从底层开始的重写：组件体系扩展到 75 个以上，其中包含 21 个新组件；同时新增 React Native 组件库，提供 37 个组件。它的技术基座也很明确：React Aria 负责可访问性语义，Tailwind CSS v4 负责样式与定制能力。

对正在维护设计系统、后台管理台或跨端产品的团队来说，这类重写意味着两件事：新项目可以获得更现代的组合方式；老项目则需要认真评估迁移成本。

这次重写真正影响的是“组件边界”

HeroUI v3 强调 accessibility 和 customization，这两个词在组件库里经常被写进介绍页，但真正落到工程里，影响的是组件边界。

基于 React Aria 的组件通常会更重视键盘交互、ARIA 属性、焦点管理等细节。对业务开发者来说，好处是少写一批容易出错的交互逻辑；代价是不能再把组件简单当成一层样式壳来随意改 DOM 结构。

Tailwind CSS v4 的加入，则把定制路径推向原子化样式和主题 token。团队如果已经使用 Tailwind，HeroUI v3 会更容易融入现有样式体系；如果团队原先依赖 CSS Modules、Less 变量或运行时主题注入，则需要重新梳理样式覆盖策略。

React 与 React Native 同时出现，说明定位变了

v3 另一个值得注意的变化，是新增 React Native 库，并带来 37 个组件。这说明 HeroUI 不再只是 Web React 场景下的组件集合，而是尝试覆盖更完整的前端产品面。

不过这里要保持冷静：React 和 React Native 的渲染模型不同，Web 上的 Tailwind CSS v4、ARIA 语义、DOM 事件，并不能一比一搬到 Native。可以期待设计语言和 API 风格趋同，但不应默认所有组件行为完全一致。

比较现实的采用方式是：

Web 端先用 HeroUI v3 承接表单、弹窗、菜单、数据展示等高频组件；
React Native 端在新页面或低风险模块中试用对应组件；
把设计 token、命名规范、交互状态先统一起来，而不是急着追求“一套代码跑两端”。

可以这样在新 React 项目里试用

下面是一个最小化的 Vite + React 试用方式。包名和导入路径请以你实际安装的 HeroUI v3 文档为准；这里的重点是演示 Tailwind CSS v4 项目中如何组织入口、样式和组件调用。

npm create vite@latest heroui-v3-demo -- --template react-ts
cd heroui-v3-demo
npm install
npm install tailwindcss @tailwindcss/vite
# 按 HeroUI v3 官方文档安装对应包，例如：
# npm install @heroui/react
npm run dev

如果你使用 Vite，可以这样接入 Tailwind CSS v4 插件：

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

入口样式可以保持非常薄：

/* src/index.css */
@import 'tailwindcss';

body {
  margin: 0;
  min-height: 100vh;
}

然后在页面里放一个“可替换”的组件示例。假设你的 HeroUI v3 包暴露了 Button、Card 这类常见组件，可以这样实践：

// src/App.tsx
import { useState } from 'react';
// 请按实际文档调整导入路径
// import { Button, Card, CardBody } from '@heroui/react';

function DemoCard() {
  const [count, setCount] = useState(0);

  return (
    <main className="min-h-screen bg-zinc-950 p-8 text-zinc-100">
      <section className="mx-auto max-w-xl rounded-2xl border border-zinc-800 bg-zinc-900 p-6 shadow-lg">
        <p className="mb-2 text-sm text-zinc-400">HeroUI v3 trial</p>
        <h1 className="mb-4 text-2xl font-semibold">验证组件、主题和交互边界</h1>
        <p className="mb-6 text-zinc-300">
          先用一个低风险页面检查 Tailwind v4 样式、组件 API、键盘操作和暗色主题是否符合团队预期。
        </p>
        <button
          className="rounded-xl bg-blue-500 px-4 py-2 font-medium text-white hover:bg-blue-400 focus:outline-none focus:ring-2 focus:ring-blue-300"
          onClick={() => setCount((value) => value + 1)}
        >
          点击次数：{count}
        </button>
      </section>
    </main>
  );
}

export default DemoCard;

这段代码故意先使用原生 button 和 Tailwind class。迁移到 HeroUI 组件时，可以逐个替换：先替换 Button，再替换 Card、Modal、Dropdown、Input 等复杂组件。这样做的好处是，样式系统和组件系统的问题不会混在一起。

老项目迁移不要只看“能不能编译”

来源摘要明确提到：从旧版本迁移到 v3 是必要的。由于 v3 是 ground-up rewrite，迁移时不能只跑一次 TypeScript 编译就结束。

建议建立一张迁移清单：

组件 API：检查 props 是否改名、删除或语义变化；
样式覆盖：旧的 className、CSS 选择器、主题变量是否仍然生效；
可访问性行为：弹窗焦点锁定、菜单键盘导航、表单错误提示是否符合预期；
视觉回归：按钮高度、间距、圆角、暗色模式都要截图比对；
包体积与构建：Tailwind CSS v4 配置变化可能影响构建链路；
跨端边界：React Native 组件不要假设与 Web 组件完全同构。

可以先用命令把旧项目里依赖组件库的位置扫出来：

# 根据旧项目实际包名调整，例如 nextui、@nextui-org 或 heroui
rg "nextui|@nextui|heroui|@heroui" src

# 找出直接覆盖组件内部结构的样式，迁移时优先检查
rg "data-\[|aria-|\.nextui|\.heroui" src

采用建议：新项目大胆试，核心系统分阶段迁

HeroUI v3 的方向很清晰：用 React Aria 打可访问性基础，用 Tailwind CSS v4 打定制基础，再把 React 和 React Native 都纳入组件版图。它适合那些希望减少基础组件维护成本、同时又不想放弃主题控制权的团队。

但重写版本也意味着边界重新划定。对生产系统，推荐按下面节奏推进：

选一个非核心页面做 POC，验证构建、主题、暗色模式和交互；
优先迁移低状态组件，例如 Button、Badge、Card；
再迁移高交互组件，例如 Modal、Dropdown、Select、Table；
每一批都做键盘操作和视觉回归测试；
React Native 端单独评估，不要把 Web 迁移结论直接套过去。

把 HeroUI v3 当成一次设计系统升级，而不是一次 npm 包升级，迁移过程会稳很多。