HeroUI（原名 NextUI）是一个基于 React 的现代化 UI 组件库。在 2026 年发布的 v3 版本是整个项目的完全重写，不仅是名字的更换，背后是整个设计哲学的升级。
为什么值得关注？
组件数量：75+ 个（并持续增加中）
核心依赖：React Aria（无障碍支持）+ Tailwind CSS v4（样式系统）
独特优势：官方 Figma Kit + MCP Server（AI 编程友好）
一、工程化入门：5 分钟跑起来
1.1 创建项目并安装
HeroUI 针对现代工程化场景提供了 CLI 工具，比传统的 npm 安装 + 手动配置更智能。
# 创建 Next.js 项目（推荐）
npx create-next-app@latest my-app --typescript --tailwind
# 进入项目
cd my-app
# 使用 HeroUI CLI 初始化
npx heroui-cli@latest init
CLI 自动做了什么？
http://uklgy.cn
检测包管理器（npm/yarn/pnpm）
安装 @heroui/react、framer-motion
在 tailwind.config.js 中自动添加 HeroUI 插件配置
配置 postcss.config.js 以支持 Tailwind v4
如果你使用 pnpm，CLI 还会自动在 .npmrc 中添加：
public-hoist-pattern[]=*@heroui/*
这是为了避免幽灵依赖问题。
1.2 配置 Tailwind
检查你的 tailwind.config.js，应该已经包含以下配置：
import { heroui } from "@heroui/react";
/** @type {import('tailwindcss').Config} */
export default {
content: [
"./pages/**/*.{js,ts,jsx,tsx,mdx}",
"./components/**/*.{js,ts,jsx,tsx,mdx}",
"./app/**/*.{js,ts,jsx,tsx,mdx}",
// 关键：引入 HeroUI 组件的路径
"./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}"
],
theme: {
extend: {},
},
darkMode: "class",
plugins: [heroui()]
}
注意：darkMode: "class" 是必需的，HeroUI 通过添加 .dark 类来切换暗色主题。
1.3 Provider 配置
在应用的根组件中包裹 HeroUIProvider：
// app/providers.tsx
"use client";
import { HeroUIProvider } from "@heroui/react";
import { useRouter } from "next/navigation";
export function Providers({ children }: { children: React.ReactNode }) {
const router = useRouter();
return (
<HeroUIProvider navigate={router.push}>
{children}
</HeroUIProvider>
);
}
关于 navigate 参数：这是 Next.js App Router 特有的配置，用于让 Modal、Popover 等组件内的导航链接正确使用客户端路由，而不是整页刷新。
1.4 测试组件
// app/page.tsx
import { Button, Card, CardBody } from "@heroui/react";
export default function Home() {
return (
<Card className="max-w-md mx-auto mt-20">
<CardBody className="text-center space-y-4">
<h1 className="text-2xl font-bold">欢迎使用 HeroUI！</h1>
<Button color="primary" variant="shadow">
点击我
</Button>
</CardBody>
</Card>
);
}
运行 npm run dev，看到效果了吗？恭喜，环境配置成功！
