45. 源文件检测配置

Tailwind 的工作原理是扫描你的源文件，只生成实际用到的类的 CSS。理解这个机制，就不会再遇到”我写了类名但样式不生效”的问题了。

自动检测原理

Tailwind 把源文件当作纯文本扫描，寻找可能的类名标记：

// Tailwind 会扫描这个文件，找到所有可能的类名
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>
  );
}

扫描后生成这些类：bg-black、text-white、bg-blue-500、bg-white、text-black、rounded-full、px-2、py-1.5、font-sans、text-sm/6、font-medium、shadow。

哪些文件会被扫描

默认情况下，Tailwind 会扫描所有文件，除了：

• .gitignore 中列出的文件
• node_modules 目录
• 二进制文件（图片、视频、压缩包等）
• CSS 文件
• 包管理器锁文件（package-lock.json、yarn.lock 等）

动态类名的陷阱

Tailwind 不理解字符串拼接，所以动态构造的类名不会被检测到：

// 错误：Tailwind 检测不到 text-red-600 或 text-green-600
<div className={`text-${error ? 'red' : 'green'}-600`}>
  这段文字不会变色
</div>

正确做法是使用完整的类名：

// 正确：完整的类名可以被检测到
<div className={error ? 'text-red-600' : 'text-green-600'}>
  这段文字会变色
</div>

或者使用映射对象：

// 正确：映射到完整类名
const colorMap = {
  error: 'text-red-600',
  success: 'text-green-600',
  warning: 'text-yellow-600',
};
<div className={colorMap[status]}>根据状态变色</div>

@source 指令

@source 让你可以显式控制源文件的扫描行为。

添加额外扫描路径

/* 扫描 node_modules 中的 UI 库 */
@source "../node_modules/@acmecorp/ui-lib";

/* 扫描多个路径 */
@source "../shared/components";
@source "../admin/views";

设置基础路径

/* 设置源文件扫描的基础路径 */
@import "tailwindcss" source("../src");

在 monorepo 中很有用，可以避免扫描其他项目的文件。

排除特定路径

/* 排除 legacy 组件目录 */
@source not "../src/components/legacy";

/* 排除多个路径 */
@source not "../src/legacy";
@source not "../src/vendor";

禁用自动检测

/* 完全禁用自动检测，手动指定所有源 */
@import "tailwindcss" source(none);
@source "../admin";
@source "../shared";
@source "../public";

适用于有多个独立样式表的项目，每个表只包含自己需要的类。

安全列表（Safelist）

有时你需要强制生成某些类，即使源文件中没有直接出现。使用 @source inline()：

强制生成单个类

/* 强制生成 underline 类 */
@source inline("underline");

强制生成带变体的类

/* 生成 underline 及其 hover、focus 变体 */
@source inline("{hover:,focus:,}underline");

使用范围批量生成

/* 生成所有红色背景色及其 hover 变体 */
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");

这会生成：bg-red-50、bg-red-100、bg-red-200…bg-red-950，以及每个类的 hover: 变体。

范围语法说明：

{100..900..100}  → 从 100 到 900，步长 100
{50,100,200}     → 具体值列表

排除特定类

/* 排除红色背景色 */
@source not inline("{hover:,focus:,}bg-red-{50,{100..900..100},950}");

即使源文件中使用了这些类，也不会生成对应的 CSS。

实际应用场景

场景 1：扫描外部 UI 库

@import "tailwindcss";
@source "../node_modules/@my-company/design-system";

场景 2：动态类名的安全列表

@import "tailwindcss";

/* 如果有些类名是 JS 动态生成的，需要手动添加到安全列表 */
@source inline("{hover:,}bg-{red,green,yellow}-500");
@source inline("text-{xs,sm,base,lg,xl}");

场景 3：多主题项目

/* admin.css - 只包含后台需要的类 */
@import "tailwindcss" source(none);
@source "../admin";
@source "../shared";

/* marketing.css - 只包含营销页面需要的类 */
@import "tailwindcss" source(none);
@source "../marketing";
@source "../shared";

场景 4：monorepo 配置

/* 在 monorepo 根目录运行，只扫描当前项目 */
@import "tailwindcss" source("../packages/web");

调试类名检测

如果某个类名没有生效，检查以下几点：

1. 类名是否完整出现在源文件中：搜索确认
2. 文件是否被扫描：检查是否在 .gitignore 中
3. 是否有拼写错误：bg-red-500 不是 bg-red500
4. 是否被排除规则过滤：检查 @source not 配置

源文件检测是 Tailwind 性能优化的核心——只生成用到的 CSS，不浪费。把它搞清楚，大部分”类名不生效”的问题都能迎刃而解。