Lzh on GitHub

检测源文件中的类名

理解和自定义 Tailwind 如何扫描你的源文件。

概述

Tailwind 的工作原理是扫描你的项目以查找工具类名，然后根据你实际使用的类名生成所有必要的 CSS。

这确保了你的 CSS 文件尽可能的小，并且也是像 任意值 等功能实现的基础。

类名是如何被检测的

Tailwind 将你的所有源文件视为纯文本，并且不会尝试以任何方式实际解析你的文件作为代码。

相反，它只是在你的文件中查找任何可能作为类名的标记，这些标记基于 Tailwind 期望在类名中出现的字符：

JSX
export function Button({ color, children }) {
  const colors = {
    black: "bg-black text-white",
    blue: "bg-blue-500 text-white",
    white: "bg-white text-black",
  };
  return (
    <button className={`${colors[color]} rounded-full px-2 py-1.5 font-sans text-sm/6 font-medium shadow`}>
      {children}
    </button>
  );
}

然后它尝试为所有这些标记生成 CSS，丢弃任何不映射到框架已知的工具类名的标记。

动态类名

由于 Tailwind 将你的源文件作为纯文本扫描，因此它无法理解你正在使用的编程语言中的字符串连接或插值。

不要动态构建类名
HTML
<div class="text-{{ error ? 'red' : 'green' }}-600"></div>

在上面的示例中，字符串 text-red-600 和 text-green-600 并不存在，因此 Tailwind 不会生成这些类名。

相反，请确保你使用的任何类名都完整存在：

始终使用完整的类名
<div class="{{ error ? 'text-red-600' : 'text-green-600' }}"></div>

如果你使用的是像 React 或 Vue 这样的组件库，这意味着你不应该使用 props 来动态构建类名：

不要使用 props 来动态构建类名
JSX
function Button({ color, children }) {
  return <button className={`bg-${color}-600 hover:bg-${color}-500 ...`}>{children}</button>;
}

相反，将 props 映射到在构建时可以静态检测到的完整类名：

始终将 props 映射到静态类名
JSX
function Button({ color, children }) {
  const colorVariants = {
    blue: "bg-blue-600 hover:bg-blue-500",
    red: "bg-red-600 hover:bg-red-500",
  };
  return <button className={`${colorVariants[color]} ...`}>{children}</button>;
}

这样做的好处是，例如，你可以将不同的 prop 值映射到不同的颜色深浅：

JSX
function Button({ color, children }) {
  const colorVariants = {
    blue: "bg-blue-600 hover:bg-blue-500 text-white",
    red: "bg-red-500 hover:bg-red-400 text-white",
    yellow: "bg-yellow-300 hover:bg-yellow-400 text-black",
  };
  return <button className={`${colorVariants[color]} ...`}>{children}</button>;
}

只要你始终在代码中使用完整的类名，Tailwind 每次都会完美地生成你的所有 CSS。

哪些文件会被扫描

Tailwind 将扫描你项目中的每个文件以查找类名，以下情况除外：

  • 你的 .gitignore 文件中的文件
  • 二进制文件，如图像、视频或 zip 文件
  • CSS 文件
  • 常见的包管理器 lock 文件

如果你需要扫描 Tailwind 默认忽略的任何文件，你可以 显式注册 这些源文件。

显式注册源文件

使用 @source 显式注册相对于样式表文件的源路径：

CSS
@import "../../../../../node_modules/.pnpm/tailwindcss@4.1.11/node_modules/tailwindcss/dist/lib.d.mts";

@source "../node_modules/@acmecorp/ui-lib";

当你需要扫描使用 Tailwind 构建的外部库时，这尤其有用，因为依赖项通常列在你的 .gitignore 文件中，并且默认情况下会被 Tailwind 忽略。

设置你的基础路径

Tailwind 默认使用当前工作目录作为扫描类名的起点。

要显式设置源检测的基础路径，在你的 CSS 中导入 Tailwind 时使用 source() 函数：

CSS
@import "tailwindcss" source("../src");

当你在 monorepo 中工作时，你的构建命令从 monorepo 的根目录而不是每个项目的根目录运行时，这非常有用。

忽略特定的路径

使用 @source not 在扫描类名时忽略相对于样式表的特定路径：

CSS
@import "tailwindcss";
@source not "../src/components/legacy";

当你的项目中存在你知道不使用 Tailwind 类的庞大目录（例如旧组件或第三方库）时，这非常有用。

禁用自动检测

如果你想显式注册所有源文件，可以使用 source(none) 完全禁用自动源检测：

CSS
@import "tailwindcss" source(none);

@source "../admin";
@source "../shared";

这在具有多个 Tailwind 样式表的项目中非常有用，你希望确保每个样式表仅包含其需要的类名。

安全地列出特定的工具类

如果你需要确保 Tailwind 生成某些在你的内容文件中不存在的类名，请使用 @source inline() 强制生成它们：

CSS
@import "tailwindcss";
@source inline("underline");
Generated CSS
.underline {
  text-decoration: underline;
}

安全地列出变体

你还可以使用 @source inline() 生成带有变体的类名。例如，要生成带有 hover 和 focus 变体的 underline 类，请将 {hover:,focus:,} 添加到源输入：

CSS
@import "tailwindcss";
@source inline("{hover:,focus:,}underline");
Generated CSS
.underline {
  text-decoration: underline;
}
@media (hover: hover) {
  .hover\:underline:hover {
    text-decoration: underline;
  }
}
@media (focus: focus) {
  .focus\:underline:focus {
    text-decoration: underline;
  }
}

使用范围进行安全地列出

源输入是 大括号展开 的，因此你可以一次生成多个类名。例如，要生成所有带有 hover 变体的红色背景颜色，请使用范围：

CSS
@import "tailwindcss";
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");
Generated CSS
.bg-red-50 {
  background-color: var(--color-red-50);
}
.bg-red-100 {
  background-color: var(--color-red-100);
}
.bg-red-200 {
  background-color: var(--color-red-200);
}

/* ... */

.bg-red-800 {
  background-color: var(--color-red-800);
}
.bg-red-900 {
  background-color: var(--color-red-900);
}
.bg-red-950 {
  background-color: var(--color-red-950);
}
@media (hover: hover) {
  .hover\:bg-red-50:hover {
    background-color: var(--color-red-50);
  }
  
  /* ... */
  
  .hover\:bg-red-950:hover {
    background-color: var(--color-red-950);
  }
}

这将生成从 100 到 900 步长为 100 的红色背景颜色，以及第一个和最后一个色阶 50 和 950。它还为每个类添加了 hover: 变体。

显式排除类名

使用 @source not inline() 阻止生成特定的类名，即使它们在你的源文件中被检测到：

CSS
@import "tailwindcss";
@source not inline("{hover:,focus:,}bg-red-{50,{100..900..100},950}");

这将显式排除红色背景工具类及其 hover 和 focus 变体被生成。