Tailwind CSS - 内容配置

Tailwind CSS：Content 配置

tailwind.config.js 文件中的 content 配置是现代 Tailwind CSS 最关键的设置。它告诉 Tailwind 的即时 (JIT) 引擎要扫描哪些文件以查找类名。然后 Tailwind 只生成你在项目中实际使用的 CSS，从而产生一个高度优化、可用于生产环境的样式表。

配置你的源路径

content 键接受一个 glob 模式数组来匹配你的模板文件。关键在于要全面，并包含所有包含 Tailwind 类名的文件的路径，例如 HTML 文件、JavaScript 组件（React、Vue、Svelte）以及任何其他模板源。

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx}',
    './src/components/**/*.{js,ts,jsx,tsx}',
    './public/index.html' // 如果你有一个根 HTML 文件
  ],
  // ...
}

模式配置最佳实践

具体化： 提供尽可能具体的路径。避免使用过于宽泛的模式，例如 './**/*.{js,html}'，这可能会不必要地扫描 node_modules 或构建输出目录，从而减慢你的构建速度。
包含所有扩展名： 确保包含所有相关文件扩展名。对于一个 React/TypeScript 项目，你需要 {js,ts,jsx,tsx}。
框架特定路径： 不同的框架有不同的文件结构。例如，一个 Next.js 项目可能会使用 './app/**/*.{js,ts,jsx,tsx}' 和 './components/**/*.{js,ts,jsx,tsx}'。
绝不要包含 CSS 文件： 不要在 content 路径中包含你的 CSS 文件。这可能会导致无限构建循环。

Tailwind 如何检测类

Tailwind 不会解析或执行你的代码。它使用正则表达式静态扫描你的文件，查找任何看起来像 Tailwind 类的字符串。这对你编写类的方式有重要影响。

黄金法则：不要动态构造类名

由于 Tailwind 扫描的是完整、不间断的类字符串，因此你必须避免通过拼接字符串来创建类名。Tailwind 需要在你的源文件中看到完整的类名，才能生成相应的 CSS。

// 一个接受 color 属性的组件
function Alert({ color, children }) {

  // ❌ 不要这样做：Tailwind 将找不到这些类
  const colorClass = `bg-${color}-500`; // 例如，'bg-red-500'
  return <div className={colorClass}>{children}</div>;

  // ✅ 而是这样做：使用一个映射来保存完整的类名
  const colorMap = {
    red: 'bg-red-500 text-red-100',
    blue: 'bg-blue-500 text-blue-100',
  };
  return <div className={colorMap[color]}>{children}</div>;

  // ✅ 或者这样做：让三元表达式选择完整的类名
  return <div className={color === 'red' ? 'bg-red-500' : 'bg-blue-500'}>{children}</div>;
}

高级配置选项

安全列表（Safelisting）类

在极少数情况下，你可能需要确保某些类始终包含在最终的 CSS 中，即使它们无法在你的 content 文件中找到（例如，它们来自数据库）。为此使用 safelist 选项。谨慎使用，因为它会增加最终 CSS 包的大小。

module.exports = {
  // ...
  safelist: [
    'bg-red-500',
    'bg-green-500',
    'bg-blue-500',
    { // 你也可以使用正则表达式来安全列表模式
      pattern: /bg-(red|green|blue)-(100|200|300)/,
      variants: ['hover', 'focus'], // 并为它们包含变体
    },
  ],
}

样式化第三方库

如果第三方库渲染的 HTML 你无法直接添加类，你有两个主要选项：

使用 CSS 定位： 在你的主 CSS 文件中使用 @layer，通过 @apply 来样式化库的选择器。这是经典方法。
包含库源文件： 如果库的源文件位于 node_modules 中并且包含 Tailwind 类，你可以在 content 配置中添加它们的路径。这对于设计为使用 Tailwind 进行样式化的“无头” UI 库来说很常见。

const path = require('path');

module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // 包含来自无头 UI 库的类
    path.join(path.dirname(require.resolve('@headlessui/react')), '**/*.{js,ts,jsx,tsx}'),
  ],
  // ...
}

常见问题排查

类不生效： 最常见的原因是 content 路径配置错误。仔细检查你的 glob 模式和文件扩展名。确保你已包含所有源目录。
样式在生产环境中消失： 如果样式在开发环境中有效但在生产环境中无效，这几乎总是 content 配置问题。你的生产构建过程正在清除它找不到的类。请回顾“不要动态构造类名”的规则。
构建时间慢： 如果你的构建速度慢，你的 content 路径可能过于宽泛。避免扫描 node_modules 或不包含任何类的大型目录。