daisyUI 在 React 项目中的集成指南：安装、插件机制与主题原理

本文以 daisyUI 官方文档中「React component library」页面为核心，讲解如何在 React 项目（以 Vite 工具链为例）中安装并启用 daisyUI，并结合 daisyui 包入口 与 插件参数处理器 的源码，说明 @plugin "daisyui" 这一行配置背后到底发生了什么、主题变量与组件类名是如何注入到 Tailwind CSS 构建流程中的。读完后你可以独立完成 daisyUI 在 React 项目中的接入，并理解其"纯 CSS、零 JS 依赖"设计在 React 架构下的具体含义。

一、daisyUI 在 React 中的定位：只做 CSS，不接管组件行为

daisyUI 官方对 React 场景的总结是：daisyUI 提供带样式的组件，但不接管组件行为——React 继续负责状态、事件、表单、路由和数据流，daisyUI 只负责 CSS 层。这个分工在实际的 React 代码中有四点具体收益：

• 无 JavaScript 依赖：daisyUI 不会向你的打包产物里添加任何 React 组件、Hooks、Provider 或客户端状态逻辑。从源码看这一点可以佐证：daisyui 包 的入口是 index.js，它是一个 Tailwind CSS 插件（见下文第三节），browser 字段指向 daisyui.css（预构建的 CSS 产物），没有任何运行时的 React 代码。
• 可读的 JSX：btn、card、alert、input 这类语义化类名让重复出现的 UI 结构比一长串原子类更容易扫读和维护。
• 行为归框架所有：弹窗怎么打开、表单如何校验、菜单数据从哪来，都由你的 React 组件决定；daisyUI 只负责给标记（markup）上样式。
• 默认可主题化：内置主题和 CSS 变量让亮色、暗色与品牌主题可以低成本切换，而不需要重写每个组件的样式。

对 React 团队来说，这意味着设计层提速的同时，应用架构仍完全掌握在自己手中。这一点是 daisyUI 与"React 组件库"（如提供 <Button> 组件方案的库）的本质区别：它是 Tailwind CSS 的组件类名层，而不是组件运行时层。

二、React 项目安装 Tailwind CSS 与 daisyUI

daisyUI 的 React 安装路径与任何 Tailwind CSS 4 项目完全一致。官方安装文档（Install daisyUI for React/docs/install/react/+page.md)）给出了三步操作：

1. 创建 React 项目

在当前目录创建 Vite React 项目：

npm create vite@latest ./ -- --template react

2. 安装 Tailwind CSS 与 daisyUI

npm install tailwindcss@latest @tailwindcss/vite@latest daisyui@latest

注意这里同时安装了 @tailwindcss/vite，它是 Tailwind CSS 4 官方提供的 Vite 集成插件。当前仓库中 daisyui 包的版本为 5.7.27（见 package.json）。

3. 配置 Vite 与 CSS 入口

把 Tailwind CSS 加入 Vite 配置：

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

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

然后在 CSS 入口文件中引入 Tailwind CSS 并挂载 daisyUI 插件（同时移除 Vite 模板自带的旧样式）：

/* src/App.css */
@import "tailwindcss";
@plugin "daisyui";

这两行就是整个集成的关键：@import "tailwindcss" 引入 Tailwind CSS 4 的基础层，@plugin "daisyui" 则把 daisyui 包作为 Tailwind 插件加载进构建流程。完成后即可在 JSX 中直接使用 daisyUI 的组件类名，例如：

// 一个最小示例：daisyUI 只负责样式，交互状态仍由 React 管理
function App() {
  const [open, setOpen] = useState(false);
  return (
    <div className="card w-96 bg-base-100 shadow-xl">
      <div className="card-body">
        <h2 className="card-title">Welcome to daisyUI</h2>
        <p className="text-sm opacity-70">Styled by CSS variables, driven by React.</p>
        <div className="card-actions">
          <button className="btn btn-primary" onClick={() => setOpen(!open)}>
            Toggle
          </button>
        </div>
      </div>
    </div>
  );
}

在这个示例里可以清楚看到文档强调的分工：btn、card、btn-primary 等类名来自 daisyUI 的 CSS，而 open 状态与点击事件完全属于 React。

三、@plugin "daisyui" 背后：插件加载链路（源码级）

理解下面这段源码，就能回答"@plugin "daisyui" 执行时发生了什么"。packages/daisyui/index.js 导出的是一个 Tailwind 插件工厂：

export default plugin.withOptions(
  (options) => {
    return ({ addBase, addComponents, addUtilities, addVariant }) => {
      const { include, exclude, prefix = "" } =
        pluginOptionsHandler(options, addBase, themesObject, version)
      // ……按 include/exclude 过滤后，依次注入 base / components / utilities
    }
  },
  () => ({ theme: { extend: variables } }),
)

可以读出三个关键事实：

1. 它是纯 Tailwind 插件。daisyUI 通过 plugin.withOptions 暴露自己，在构建期通过 addBase / addComponents / addUtilities / addVariant 四个钩子向 Tailwind 注入样式，没有任何运行时代码，这正是"无 JavaScript 依赖"结论的来源。
2. 注入内容分三类：base、components、utilities 三个对象分别来自 imports.js（构建时由 src/components、src/base、src/utilities 下的 CSS 文件编译生成），每类都支持 include / exclude 过滤和 prefix 前缀。
3. 主题变量通过 theme.extend 合并进 Tailwind 主题，即 daisyUI 的颜色（base-100、primary 等）会成为 Tailwind 可用的主题 token。

此外，入口文件还额外注册了两个 drawer 专用变体（源码注释说明它们不能嵌套在 layer 中，因此单独定义）：

addVariant(
  `${prefix}is-drawer-close`,
  `&:where(.${prefix}drawer-toggle:not(:checked) ~ .${prefix}drawer-side, ...)`
)
addVariant(
  `${prefix}is-drawer-open`,
  `&:where(.${prefix}drawer-toggle:checked ~ .${prefix}drawer-side, ...)`
)

这与 drawer.css 中 .drawer-toggle 的 checkbox 方案相呼应：抽屉的开合状态由隐藏的 checkbox 勾选态驱动，纯 CSS 即可完成，React 组件只需控制该 checkbox 的 checked 值或类名。

四、主题机制：--default 与 --prefersdark 的默认值

很多人只写 @plugin "daisyui"; 一行却拿到了亮/暗双主题，原因在 pluginOptionsHandler.js 中的默认参数：

const {
  logs = true,
  root = ":root",
  themes = ["light --default", "dark --prefersdark"],
  include,
  exclude,
  prefix = "",
} = options || {}

默认启用 light（作为默认主题）和 dark（跟随系统 prefers-color-scheme）。处理器根据 flag 生成不同选择器：

• --default 主题会附加 :where(:root) 选择器，即直接落在根节点上；
• --prefersdark 主题会包在 @media (prefers-color-scheme: dark) 中，并选择 :root:not([data-theme])，避免被显式指定的主题覆盖；
• 普通主题则绑定 [data-theme=主题名] 以及 :root:has(input.theme-controller[value=主题名]:checked) 两种选择器——后者支持用一组 radio 做"主题控制器"（theme controller）。

也就是说，在 React 应用中切换主题，只需要修改根元素的 data-theme 属性，例如 document.documentElement.setAttribute("data-theme", "cupcake")，无需重新加载任何 JS 组件。主题本身只是一组 CSS 变量，以 light.css 为例：

color-scheme: light;
--color-base-100: oklch(100% 0 0);
--color-base-200: oklch(98% 0 0);
--color-base-content: oklch(21% 0.006 285.885);
--color-primary: oklch(45% 0.24 277.023);
/* ……更多语义色变量 */

所有颜色都是 oklch() 格式的 CSS 变量，这解释了文档中"themeable by default"的实现方式：换主题 = 换一组变量，组件样式零改动。

五、组件类名如何工作：以 btn 为例

以 button.css 为样本，可以看到 daisyUI 组件类的设计模式：

.btn {
  @layer daisyui.l1.l2.l3 {
    --size: calc(var(--size-field, 0.25rem) * 10);
    --btn-bg: var(--btn-color, var(--color-base-200));
    --btn-border: color-mix(in oklab, var(--btn-color, var(--color-base-200)),
      #000 calc(var(--depth) * 5%));
    /* ……内联 flex 布局、过渡、圆角等，全部基于 CSS 变量 */
    @apply inline-flex shrink-0 cursor-pointer flex-nowrap items-center ...;
  }
}

两个值得注意的工程细节：

• 样式写在 daisyui.l1.l2.l3 layer 内：daisyUI 把组件样式放进 CSS @layer，让 Tailwind 的工具类（utilities layer）在优先级上天然覆盖组件类。因此在 React JSX 里用 btn rounded-lg px-4 这类工具类微调，不需要 ! 重要级前缀。
• 颜色层层引用变量：--btn-bg 默认取 --color-base-200，而 --color-base-200 来自当前激活主题。变体类（如 btn-primary）只需要设置 --btn-color，边框、阴影再由 color-mix() 从背景色自动推导。这套"变量 → 变体"链路就是主题可换肤的底层原因。

仓库中共有 60 余个组件的 CSS 实现（src/components 目录），以及 glass、join 等工具层实现（src/utilities），类名与 文档站组件页/components) 一一对应。

六、@plugin "daisyui" 可配置的参数

如果只写 @plugin "daisyui";，将使用全部默认值。在 CSS 中也可以用带花括号的语法传入插件选项：

@plugin "daisyui" {
  themes: "light", "dark"; /* 只编译这两个主题 */
  /* logs: false;          构建时不打印 daisyUI 版本横幅 */
  /* root: ":root";        主题变量的挂载选择器 */
  /* include: ["btn"];     白名单：只编译按钮相关组件 */
  /* exclude: ["alert"];   黑名单：排除指定组件 */
  /* prefix: "myui-";      类名前缀，避免与现有类名冲突 */
}

各参数的默认值与行为均可以从 pluginOptionsHandler.js 确认：

参数	默认值	说明
themes	["light --default", "dark --prefersdark"]	要编译的主题列表；支持 "all" 编译全部内置主题；--default 标记默认主题，--prefersdark 标记跟随系统暗色的主题
root	":root"	主题 CSS 变量挂载的选择器，也用于 --prefersdark 的 :not([data-theme]) 选择器构造
prefix	""	类名前缀，会同步作用于 theme-controller 选择器和 is-drawer-open 等变体
include / exclude	无	组件白名单/黑名单，二者同时存在时以白名单为准并排除黑名单项（见 index.js 中的 shouldIncludeItem 逻辑）
logs	true	首次构建时向控制台打印 daisyUI 版本号

一个实用场景：如果 React 项目中已有一组 btn 命名的业务类，可以用 prefix: "dui-" 把 daisyUI 类名隔离为 dui-btn；反之，若项目只用到少量组件，用 include 缩小编译范围也能减少最终 CSS 体积。

七、小结与验证方式

在 React 项目中接入 daisyUI 的完整心智模型可以归纳为：

1. 安装 tailwindcss@latest、@tailwindcss/vite@latest、daisyui@latest，在 vite.config.js 注册 tailwindcss() 插件；
2. CSS 入口写 @import "tailwindcss"; @plugin "daisyui";（可选参数见第六节）；
3. JSX 中使用 btn、card、alert 等类名获得样式；交互状态、事件、路由仍全部由 React 组件管理；
4. 切换主题只需改 data-theme 属性，主题即一组 oklch() 颜色的 CSS 变量。

验证集成是否生效很简单：在组件里放一个 <button className="btn btn-primary">，若能呈现带主题色的按钮，说明 Tailwind CSS 4 的 Vite 插件已正确加载 daisyUI 插件、主题变量已注入 :root。更细粒度的安装步骤可参考官方安装文档 Install daisyUI for React/docs/install/react/+page.md)，插件行为的实现细节可在 index.js 与 pluginOptionsHandler.js 中逐行对照。