Tailwind CSS

是什么，为什么存在

Tailwind CSS 是一个工具优先 CSS（utility-first CSS）框架。一个 工具类（utility class） 通常只表达一小组声明，例如 grid、p-6 或 text-slate-900；组件的最终外观来自这些类的组合。Tailwind 在构建期生成普通 CSS，浏览器里没有必须随应用运行的 Tailwind 样式引擎。

传统组件样式往往要求你先创造 .product-card 之类的名称，再去另一个文件维护声明。Tailwind 把已有的设计词汇放到使用它的标记旁边，减少一次性类名和跨文件查找。它仍然依赖 CSS 的继承、层叠和媒体查询，所以工具类不是独立于 CSS 的另一套布局系统。

工具优先方法最适合有限且共享的设计系统：间距、颜色、字号、圆角和断点来自同一套令牌，组件只选择允许的组合。重复的是类名文本，而不是生成后的规则；相同候选类通常只对应一条 CSS 规则。需要复杂选择器、内容驱动样式或第三方组件覆盖时，普通 CSS 仍然是正确工具。

你会在 HTML 模板、React 或 Vue 组件以及服务端模板中遇到 Tailwind 类名。框架不会理解这些文件的编程语言，它把源码当作文本寻找可能的类名，再尝试为有效候选项生成规则。这个约束解释了 Tailwind 最常见的生产故障：开发者或模型在运行时拼出一个从未以完整形式出现在源码里的类名。

本页针对 Tailwind CSS 4.3.3。旧教程中的 npx tailwindcss init、content 数组和三个 @tailwind 指令描述的是早期主流程，不能直接当作 v4 的默认安装方式。迁移旧项目时应先确认实际主版本，再选择对应文档。

工作原理

Tailwind 的核心是“候选类名到 CSS 规则”的构建流程。构建工具加载主题和指令，源码检测器收集候选文本，编译器丢弃无法识别的候选项，并为其余项目生成规则。最终浏览器只接收 CSS，不需要知道这些规则由 Tailwind 生成。

从候选类名到规则

一次构建可以按下面的顺序理解：

1. CSS 入口导入 Tailwind，并声明项目需要的主题变量或自定义规则。
2. 源码检测器从模板与组件中收集看起来可能是类名的文本。
3. 编译器把 md:hover:bg-indigo-700 拆成工具与条件变体。
4. 主题命名空间为颜色、间距、断点或圆角工具提供值。
5. 构建输出进入普通 CSS 层叠，由浏览器匹配元素与当前状态。

源码检测（source detection） 不是 JavaScript 求值，也不是 AST 类型检查。检测器可以看见字符串字面量 bg-red-600，却不能推导 `bg-${tone}-600` 的可能结果。候选项只有在检测阶段可见，或通过 @source 明确注册，才有机会生成规则。

工具、变体与任意值

一个候选类名通常由可选 变体（variant） 、工具名和修饰值组成。hover:bg-indigo-700 表示仅在悬停条件成立时应用背景色工具；md:grid-cols-2 把网格列数工具包在最小宽度媒体查询中。变体可以堆叠，但每一段仍须是编译器识别的完整文本。

方括号中的任意值用于设计系统没有表达的真实例外，例如来自运行时 CSS 自定义属性的值。它们不是绕过令牌设计的快捷方式。大量近似颜色、像素宽度和复杂表达式会把隐含的设计系统分散到标记中，使审查与全局修改变难。

主题变量

主题变量（theme variable） 是在顶层 @theme 中声明的特殊 CSS 变量。它们既会成为生成 CSS 中的自定义属性，也会决定哪些工具存在；例如 --color-brand-600 可启用 bg-brand-600 等颜色工具，--radius-card 可启用 rounded-card。

普通 :root 自定义属性只有浏览器语义，不会单独创建 Tailwind 工具。需要一个令牌映射到工具 API 时用 @theme；只需要运行时层叠值时用 :root 或组件作用域变量。两者可以结合，例如任意值工具读取 var(--panel-opacity)。

主题变量让工具词汇与设计令牌保持联系，但命名仍是公共接口。删除或重命名变量可能让对应候选项不再生成。共享组件库应记录它要求的主题命名空间，并在使用方的生产构建中测试。

响应式与状态条件

Tailwind 的响应式变体采用移动优先的最小宽度规则。无前缀工具是所有宽度的基线，md: 从 md 断点开始覆盖，xl: 再从更宽的范围覆盖。sm: 不是“手机样式”，而是从默认主题的 sm 最小宽度开始生效的条件。

状态变体把伪类、媒体特性、属性或结构关系编码在候选项中。hover:、focus-visible:、disabled:、dark:、motion-reduce:、group-* 与 peer-* 都是在条件满足时激活工具。它们只能改变视觉规则，不能为 div 补出按钮语义、键盘行为或可访问名称。

响应式规则也不应代替内容顺序设计。order-*、Grid 定位或隐藏工具可以改变视觉结果，却不会自动产生正确的 DOM、阅读和焦点顺序。每个断点都应使用真实内容、键盘操作和文本缩放验证。

源码边界与组件边界

Tailwind v4 默认自动检测项目源码，同时忽略 .gitignore 文件、依赖目录、二进制文件、CSS 文件和常见锁文件。Monorepo 或外部组件包中的类可能落在自动边界之外，可以用相对于样式表的 @source 注册路径。source(none) 适合需要完全显式控制多个样式入口的项目。

动态状态应映射到完整的静态类名。组件可以维护 toneClasses = { danger: 'bg-red-600', safe: 'bg-green-600' }，再按属性选择映射值。这样检测器能看见候选项，代码审查也能看到允许的有限状态。

重复标记优先通过框架组件或模板局部封装，因为这会同时保存结构、行为和样式契约。@apply 可以把现有工具内联进自定义 CSS，但它会重新引入命名与样式表边界，不应只为缩短一处 class 属性而使用。复杂选择器或真正共享的第三方覆盖直接写 CSS 往往更清楚。

示例

下面四个夹具使用本地 Tailwind CSS 4.3.3 编译器执行。@source inline() 只负责让隔离文件的候选项确定可见；真实应用通常从 HTML 或组件源码自动检测这些完整类名。输出保留编译器生成的版本横幅，并且没有手工改写。

组合基础工具

第一个夹具定义卡片需要的最小主题，并请求六个完整候选项。它展示了工具如何引用主题变量，而不是把间距和颜色复制到每个组件中。

标记中无论重复多少次 p-6，这个夹具仍只需要一条 .p-6 规则。另一方面，主题里没有相应命名空间时，候选项可能无法生成；这就是令牌词汇与可用工具之间的契约。

编译交互状态

第二个夹具加入悬停、可见焦点和禁用状态。候选类名中的冒号会在选择器中转义，变体则成为媒体查询或伪类条件。

/* Each complete token can be detected without evaluating JavaScript. */
@theme {
  --spacing: 0.25rem;
  --color-indigo-600: oklch(51.1% 0.262 276.966);
  --color-indigo-700: oklch(45.7% 0.24 277.023);
  --color-white: #fff;
  --radius-lg: 0.5rem;
}

@source inline("rounded-lg bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-700 focus-visible:outline-2 disabled:opacity-50");
@tailwind utilities;

/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
@layer properties;
:root, :host {
  --spacing: 0.25rem;
  --color-indigo-600: oklch(51.1% 0.262 276.966);
  --color-indigo-700: oklch(45.7% 0.24 277.023);
  --color-white: #fff;
  --radius-lg: 0.5rem;
}
.rounded-lg {
  border-radius: var(--radius-lg);
}
.bg-indigo-600 {
  background-color: var(--color-indigo-600);
}
.px-4 {
  padding-inline: calc(var(--spacing) * 4);
}
.py-2 {
  padding-block: calc(var(--spacing) * 2);
}
.text-white {
  color: var(--color-white);
}
@media (hover: hover) {
  .hover\:bg-indigo-700:hover {
    background-color: var(--color-indigo-700);
  }
}
.focus-visible\:outline-2:focus-visible {
  outline-style: var(--tw-outline-style);
  outline-width: 2px;
}
.disabled\:opacity-50:disabled {
  opacity: 50%;
}
@property --tw-outline-style {
  syntax: "*";
  inherits: false;
  initial-value: solid;
}
@layer properties {
  @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
    *, ::before, ::after, ::backdrop {
      --tw-outline-style: solid;
    }
  }
}

编译结果没有为按钮添加 disabled 属性或键盘行为；这些仍由 HTML 与组件逻辑负责。悬停规则受 @media (hover: hover) 保护，也说明测试不能只模拟鼠标悬停。

建立移动优先网格

第三个夹具先生成单列基线，再在 md 与 xl 最小宽度上生成覆盖规则。源码里的 --breakpoint-lg 没有对应候选项，因此本次输出不包含 lg 媒体查询。

/* Unprefixed utilities are the mobile baseline. */
@theme {
  --spacing: 0.25rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
  --breakpoint-xl: 80rem;
}

@source inline("grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-4");
@tailwind utilities;

/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
:root, :host {
  --spacing: 0.25rem;
}
.grid {
  display: grid;
}
.grid-cols-1 {
  grid-template-columns: repeat(1, minmax(0, 1fr));
}
.gap-4 {
  gap: calc(var(--spacing) * 4);
}
@media (width >= 48rem) {
  .md\:grid-cols-2 {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}
@media (width >= 80rem) {
  .xl\:grid-cols-4 {
    grid-template-columns: repeat(4, minmax(0, 1fr));
  }
}

把 md:grid-cols-2 误读为“仅在中等宽度”会产生错误测试。它从 48rem 开始持续生效，直到同属性的更宽条件或其他层叠规则覆盖它。

连接主题与运行时变量

最后一个夹具让 @theme 创建品牌色与圆角工具，同时保留普通 :root 变量作为运行时透明度输入。任意值工具引用变量，不需要为每个透明度生成新类。

/* Theme variables create utilities; ordinary variables do not. */
@theme {
  --spacing: 0.25rem;
  --color-brand-600: oklch(52% 0.2 255);
  --radius-card: 0.75rem;
}

:root {
  --panel-opacity: 0.92;
}

@source inline("rounded-card bg-brand-600 p-6 opacity-[var(--panel-opacity)]");
@tailwind utilities;

/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
:root, :host {
  --spacing: 0.25rem;
  --color-brand-600: oklch(52% 0.2 255);
  --radius-card: 0.75rem;
}
:root {
  --panel-opacity: 0.92;
}
.rounded-card {
  border-radius: var(--radius-card);
}
.bg-brand-600 {
  background-color: var(--color-brand-600);
}
.p-6 {
  padding: calc(var(--spacing) * 6);
}
.opacity-\[var\(--panel-opacity\)\] {
  opacity: var(--panel-opacity);
}

如果透明度随元素实例变化，组件可设置 --panel-opacity，候选类名保持静态。这个边界避免产生无限的 opacity-[0.913] 一次性候选项，也让运行时值继续参与 CSS 层叠。

陷阱

在运行时拼接类名

修复： 把有限输入映射到完整字符串，例如 { danger: 'bg-red-600', safe: 'bg-green-600' }。必须引入检测边界外的类时，精确注册源码路径或使用范围尽可能小的 @source inline()，不要用宽泛保留列表掩盖未知状态。

把断点前缀当作设备名称

修复： 先写无前缀基线，再从内容真正需要变化的位置添加覆盖。测试断点前后各一个 CSS 像素，并加入长文本、缩放文字和真实容器宽度。

用视觉工具替代语义和焦点

修复： 操作用原生 button，导航用带 href 的链接，并明确 type。只有提供经验证的 focus-visible 替代样式后才移除默认轮廓，同时用键盘和高对比模式检查。

依赖 class 属性中的先后顺序

修复： 每个状态只发出一个负责同一属性的工具。若组件允许调用方覆盖样式，应定义明确的合并契约并测试最终计算样式，而不是靠重排字符串修复冲突。

让任意值吞掉设计系统

修复： 真正重复或具有产品含义的值提升为 @theme 令牌；高基数运行时值通过普通 CSS 自定义属性传入。代码审查中统计新增任意值，并要求每个例外说明约束来源。

把 v3 配置复制到 v4 项目

修复： 先从锁文件确认主版本。v4 的 Vite 集成安装 tailwindcss 与 @tailwindcss/vite、注册插件，并在 CSS 中使用 @import "tailwindcss"；旧项目迁移则按官方升级说明逐项处理。

延伸阅读

• Tailwind CSS：使用 Vite 安装
• Tailwind CSS：使用工具类设计样式
• Tailwind CSS：检测源码中的类名
• Tailwind CSS：主题变量
• Tailwind CSS：悬停、焦点与其他状态
• Tailwind CSS：响应式设计