配置

因为 Tailwind 是一个用于构建定制用户界面的框架，所以它在设计之初就考虑到了定制。

¥Because Tailwind is a framework for building bespoke user interfaces, it has been designed from the ground up with customization in mind.

默认情况下，Tailwind 将在项目的根目录中查找可选的 tailwind.config.js 文件，你可以在其中定义任何自定义项。

¥By default, Tailwind will look for an optional tailwind.config.js file at the root of your project where you can define any customizations.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  },
}

配置文件的每个部分都是可选的，因此你只需指定要更改的内容。任何缺失的部分都将回退到 Tailwind 的 默认配置。

¥Every section of the config file is optional, so you only have to specify what you’d like to change. Any missing sections will fall back to Tailwind’s default configuration.

​创建配置文件

¥Creating your configuration file

使用安装 tailwindcss npm 包时包含的 Tailwind CLI 工具为你的项目生成 Tailwind 配置文件：

¥Generate a Tailwind config file for your project using the Tailwind CLI utility included when you install the tailwindcss npm package:

npx tailwindcss init

这将在项目的根目录下创建一个最小的 tailwind.config.js 文件：

¥This will create a minimal tailwind.config.js file at the root of your project:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

​使用不同的文件名

¥Using a different file name

要使用 tailwind.config.js 以外的名称，请将其作为参数传递到命令行：

¥To use a name other than tailwind.config.js, pass it as an argument on the command-line:

npx tailwindcss init tailwindcss-config.js

当你使用自定义文件名时，你需要在使用 Tailwind CLI 工具编译 CSS 时将其指定为命令行参数：

¥When you use a custom file name, you will need to specify it as a command-line argument when compiling your CSS with the Tailwind CLI tool:

npx tailwindcss -c ./tailwindcss-config.js -i input.css -o output.css

如果你将 Tailwind 用作 PostCSS 插件，则需要在 PostCSS 配置中指定自定义配置路径：

¥If you’re using Tailwind as a PostCSS plugin, you will need to specify your custom configuration path in your PostCSS configuration:

module.exports = {
  plugins: {
    tailwindcss: { config: './tailwindcss-config.js' },
  },
}

或者，你可以使用 @config 指令指定你的自定义配置路径：

¥Alternatively, you can specify your custom configuration path using the @config directive:

@config "./tailwindcss-config.js";

@tailwind base;
@tailwind components;
@tailwind utilities;

在 函数和指令 文档中了解有关 @config 指令的更多信息。

¥Learn more about the @config directive in the Functions & Directives documentation.

​使用 ESM 或 TypeScript

¥Using ESM or TypeScript

你还可以在 ESM 甚至 TypeScript 中配置 Tailwind CSS：

¥You can also configure Tailwind CSS in ESM or even TypeScript:

/** @type {import('tailwindcss').Config} */
export default {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

当你运行 npx tailwindcss init 时，我们将检测你的项目是否是 ES 模块，并使用正确的语法自动生成你的配置文件。

¥When you run npx tailwindcss init, we’ll detect if your project is an ES Module and automatically generate your config file with the right syntax.

你还可以使用 --esm 标志显式生成 ESM 配置文件：

¥You can also generate an ESM config file explicitly by using the --esm flag:

npx tailwindcss init --esm

要生成 TypeScript 配置文件，请使用 --ts 标志：

¥To generate a TypeScript config file, use the --ts flag:

npx tailwindcss init --ts

​生成 PostCSS 配置文件

¥Generating a PostCSS configuration file

如果你还想在 tailwind.config.js 文件旁边生成一个基本的 postcss.config.js 文件，请使用 -p 标志：

¥Use the -p flag if you’d like to also generate a basic postcss.config.js file alongside your tailwind.config.js file:

npx tailwindcss init -p

这将在你的项目中生成一个 postcss.config.js 文件，如下所示：

¥This will generate a postcss.config.js file in your project that looks like this:

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

​脚手架整个默认配置

¥Scaffolding the entire default configuration

对于大多数用户，我们鼓励你将配置文件保持尽可能小，并且只指定你想要自定义的内容。

¥For most users we encourage you to keep your config file as minimal as possible, and only specify the things you want to customize.

如果你更愿意构建包含所有 Tailwind 默认配置的完整配置文件，请使用 --full 选项：

¥If you’d rather scaffold a complete configuration file that includes all of Tailwind’s default configuration, use the --full option:

npx tailwindcss init --full

你将获得一个与内部使用的 默认配置文件 Tailwind 相匹配的文件。

¥You’ll get a file that matches the default configuration file Tailwind uses internally.

​配置选项

¥Configuration options

​内容

¥Content

content 部分是你配置所有 HTML 模板、JS 组件和任何其他包含 Tailwind 类名称的文件的路径的地方。

¥The content section is where you configure the paths to all of your HTML templates, JS components, and any other files that contain Tailwind class names.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{html,js}',
    './components/**/*.{html,js}',
  ],
  // ...
}

在 内容配置 文档中了解有关配置内容源的更多信息。

¥Learn more about configuring your content sources in the Content Configuration documentation.

​主题

¥Theme

theme 部分是你定义调色板、字体、字体比例、边框大小、断点 - 与站点视觉设计相关的任何内容的地方。

¥The theme section is where you define your color palette, fonts, type scale, border sizes, breakpoints — anything related to the visual design of your site.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  theme: {
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

在 主题配置指南 中了解有关默认主题以及如何对其进行自定义的更多信息。

¥Learn more about the default theme and how to customize it in the theme configuration guide.

​插件

¥Plugins

plugins 部分允许你向 Tailwind 注册插件，这些插件可用于生成额外的工具、组件、基本样式或自定义变体。

¥The plugins section allows you to register plugins with Tailwind that can be used to generate extra utilities, components, base styles, or custom variants.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/typography'),
    require('tailwindcss-children'),
  ],
}

了解有关在 插件制作指南 中编写自己的插件的更多信息。

¥Learn more about writing your own plugins in the plugin authoring guide.

​预设

¥Presets

presets 部分允许你指定自己的自定义基本配置，而不是使用 Tailwind 的默认基本配置。

¥The presets section allows you to specify your own custom base configuration instead of using Tailwind’s default base configuration.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  presets: [
    require('@acmecorp/base-tailwind-config')
  ],

  // Project-specific customizations
  theme: {
    //...
  },
}

详细了解 预设文档 中的预设。

¥Learn more about presets in the presets documentation.

​前缀

¥Prefix

prefix 选项允许你为所有 Tailwind 生成的工具类添加自定义前缀。当在可能存在命名冲突的现有 CSS 之上分层 Tailwind 时，这非常有用。

¥The prefix option allows you to add a custom prefix to all of Tailwind’s generated utility classes. This can be really useful when layering Tailwind on top of existing CSS where there might be naming conflicts.

例如，你可以通过像这样设置 prefix 选项来添加 tw- 前缀：

¥For example, you could add a tw- prefix by setting the prefix option like so:

/** @type {import('tailwindcss').Config} */
module.exports = {
  prefix: 'tw-',
}

现在每个类都将使用配置的前缀生成：

¥Now every class will be generated with the configured prefix:

.tw-text-left {
  text-align: left;
}
.tw-text-center {
  text-align: center;
}
.tw-text-right {
  text-align: right;
}
/* etc. */

重要的是要了解此前缀添加在任何变体修饰符之后。这意味着具有响应式或状态修饰符（如 sm: 或 hover:）的类仍将首先具有响应式或状态修饰符，你的自定义前缀出现在冒号之后：

¥It’s important to understand that this prefix is added after any variant modifiers. That means that classes with responsive or state modifiers like sm: or hover: will still have the responsive or state modifier first, with your custom prefix appearing after the colon:

<div class="tw-text-lg md:tw-text-xl tw-bg-red-500 hover:tw-bg-blue-500">
  <!-- -->
</div>

负值的破折号修饰符应添加在你的前缀之前，因此如果你将 tw- 配置为前缀，则 -mt-8 将变为 -tw-mt-8：

¥The dash modifier for negative values should be added before your prefix, so -mt-8 would become -tw-mt-8 if you’ve configured tw- as your prefix:

<div class="-tw-mt-8">
  <!-- -->
</div>

前缀仅添加到 Tailwind 生成的类中；你自己的自定义类不会添加任何前缀。

¥Prefixes are only added to classes generated by Tailwind; no prefix will be added to your own custom classes.

这意味着如果你像这样添加自己的自定义工具：

¥That means if you add your own custom utility like this:

@layer utilities {
  .bg-brand-gradient { /* ... */ }
}

…生成的变体不会有你配置的前缀：

¥…the generated variants will not have your configured prefix:

.bg-brand-gradient { /* ... */ }
.hover\:bg-brand-gradient:hover { /* ... */ }

如果你也想为自己的工具添加前缀，只需将前缀添加到类定义中：

¥If you’d like to prefix your own utilities as well, just add the prefix to the class definition:

@layer utilities {
  .tw-bg-brand-gradient { /* ... */ }
}

​重要

¥Important

important 选项可让你控制 Tailwind 的工具是否应标记为 !important。这在将 Tailwind 与具有高特异性选择器的现有 CSS 结合使用时非常有用。

¥The important option lets you control whether or not Tailwind’s utilities should be marked with !important. This can be really useful when using Tailwind with existing CSS that has high specificity selectors.

要将工具生成为 !important，请将配置选项中的 important 键设置为 true：

¥To generate utilities as !important, set the important key in your configuration options to true:

/** @type {import('tailwindcss').Config} */
module.exports = {
  important: true,
}

现在，所有 Tailwind 的工具类都将生成为 !important：

¥Now all of Tailwind’s utility classes will be generated as !important:

.leading-none {
  line-height: 1 !important;
}
.leading-tight {
  line-height: 1.25 !important;
}
.leading-snug {
  line-height: 1.375 !important;
}
/* etc. */

这也适用于你使用 @layer utilities 指令在 CSS 中定义的任何自定义工具：

¥This also applies to any custom utilities you define in your CSS using the @layer utilities directive:

/* Input */
@layer utilities {
  .bg-brand-gradient {
    background-image: linear-gradient(#3490dc, #6574cd);
  }
}

/* Output */
.bg-brand-gradient {
  background-image: linear-gradient(#3490dc, #6574cd) !important;
}

​选择器策略

¥Selector strategy

在合并向元素添加内联样式的第三方 JS 库时，将 important 设置为 true 可能会引入一些问题。在这些情况下，Tailwind 的 !important 工具会破坏内联样式，这可能会破坏你的预期设计。

¥Setting important to true can introduce some issues when incorporating third-party JS libraries that add inline styles to your elements. In those cases, Tailwind’s !important utilities defeat the inline styles, which can break your intended design.

为了解决这个问题，你可以将 important 设置为像 #app 这样的 ID 选择器：

¥To get around this, you can set important to an ID selector like #app instead:

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  important: '#app',
}

此配置将为你的所有工具添加给定选择器的前缀，有效地增加它们的特异性，而实际上不会使它们成为 !important。

¥This configuration will prefix all of your utilities with the given selector, effectively increasing their specificity without actually making them !important.

指定 important 选择器后，你需要确保站点的根元素与其匹配。使用上面的示例，我们需要将根元素的 id 属性设置为 app，以便样式正常工作。

¥After you specify the important selector, you’ll need to ensure that the root element of your site matches it. Using the example above, we would need to set our root element’s id attribute to app in order for styles to work properly.

配置全部设置完毕并且根元素与 Tailwind 配置中的选择器匹配后，Tailwind 的所有工具都将具有足够高的特异性来击败项目中使用的其他类，而不会干扰内联样式：

¥After your configuration is all set up and your root element matches the selector in your Tailwind config, all of Tailwind’s utilities will have a high enough specificity to defeat other classes used in your project, without interfering with inline styles:

<html>
<!-- ... -->
<style>
  .high-specificity .nested .selector {
    color: blue;
  }
</style>
<body id="app">
  <div class="high-specificity">
    <div class="nested">
      <!-- Will be red-500 -->
      <div class="selector text-red-500"><!-- ... --></div>
    </div>
  </div>

  <!-- Will be #bada55 -->
  <div class="text-red-500" style="color: #bada55;"><!-- ... --></div>
</body>
</html>

使用选择器策略时，请确保包含根选择器的模板文件包含在 内容配置 中，否则在构建生产时将删除所有 CSS。

¥When using the selector strategy, be sure that the template file that includes your root selector is included in your content configuration, otherwise all of your CSS will be removed when building for production.

​重要修饰符

¥Important modifier

或者，你可以通过在开头添加 ! 字符来使任何工具变得重要：

¥Alternatively, you can make any utility important by adding a ! character to the beginning:

<p class="!font-medium font-bold">
  This will be medium even though bold comes later in the CSS.
</p>

! 始终位于工具名称的开头，在任何变体之后，但在任何前缀之前：

¥The ! always goes at the beginning of the utility name, after any variants, but before any prefix:

<div class="sm:hover:!tw-font-bold">

这在你需要增加特异性的极少数情况下很有用，因为你与某些你无法控制的样式交战。

¥This can be useful in rare situations where you need to increase specificity because you’re at war with some styles you don’t control.

​分隔符

¥Separator

separator 选项允许你自定义应该使用哪个字符来将修饰符（屏幕尺寸、hover、focus 等）与工具名称（text-center、items-end 等）分开。

¥The separator option lets you customize which character should be used to separate modifiers (screen sizes, hover, focus, etc.) from utility names (text-center, items-end, etc.).

我们默认使用冒号 (:)，但如果你使用不支持类名中特殊字符的模板语言（如 Pug），更改它可能很有用。

¥We use a colon by default (:), but it can be useful to change this if you’re using a templating language like Pug that doesn’t support special characters in class names.

/** @type {import('tailwindcss').Config} */
module.exports = {
  separator: '_',
}

​核心插件

¥Core Plugins

corePlugins 部分允许你完全禁用 Tailwind 通常默认生成的类，如果你的项目不需要它们的话。

¥The corePlugins section lets you completely disable classes that Tailwind would normally generate by default if you don’t need them for your project.

要禁用特定的核心插件，请为 corePlugins 提供一个对象，将这些插件设置为 false：

¥To disable specific core plugins, provide an object for corePlugins that sets those plugins to false:

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: {
    float: false,
    objectFit: false,
    objectPosition: false,
  }
}

如果你想将应启用的核心插件列入安全列表，请提供一个包含你要使用的核心插件列表的数组：

¥If you’d like to safelist which core plugins should be enabled, provide an array that includes a list of the core plugins you’d like to use:

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: [
    'margin',
    'padding',
    'backgroundColor',
    // ...
  ]
}

如果你想禁用所有 Tailwind 的核心插件，而只是将 Tailwind 用作处理你自己的自定义插件的工具，请提供一个空数组：

¥If you’d like to disable all of Tailwind’s core plugins and simply use Tailwind as a tool for processing your own custom plugins, provide an empty array:

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: []
}

以下是每个核心插件的列表以供参考：

¥Here’s a list of every core plugin for reference:

​使用多种配置

¥Using multiple configurations

对于需要使用不同 Tailwind 配置生成多个 CSS 文件的项目，请使用 @config 指令指定应为每个 CSS 入口点使用哪个配置文件：

¥For projects that need to generate multiple CSS files using different Tailwind configurations, use the @config directive to specify which config file should be used for each CSS entry point:

@config "./tailwind.site.config.js";

@tailwind base;
@tailwind components;
@tailwind utilities;

在 函数和指令 文档中了解有关 @config 指令的更多信息。

¥Learn more about the @config directive in the Functions & Directives documentation.

​在 JavaScript 中引用

¥Referencing in JavaScript

在你自己的客户端 JavaScript 中引用你的配置值通常很有用 - 例如，在 React 或 Vue 组件中动态应用内联样式时访问一些主题值。

¥It can often be useful to reference your configuration values in your own client-side JavaScript — for example to access some of your theme values when dynamically applying inline styles in a React or Vue component.

为简化此操作，Tailwind 提供了一个 resolveConfig 辅助程序，你可以使用它来生成配置对象的完全合并版本：

¥To make this easy, Tailwind provides a resolveConfig helper you can use to generate a fully merged version of your configuration object:

import resolveConfig from 'tailwindcss/resolveConfig'
import tailwindConfig from './tailwind.config.js'

const fullConfig = resolveConfig(tailwindConfig)

fullConfig.theme.width[4]
// => '1rem'

fullConfig.theme.screens.md
// => '768px'

fullConfig.theme.boxShadow['2xl']
// => '0 25px 50px -12px rgba(0, 0, 0, 0.25)'

请注意，这将传递我们的许多构建时依赖，从而导致更大的客户端包大小。为避免这种情况，我们建议使用像 babel-plugin-preval 这样的工具在构建时生成配置的静态版本。

¥Note that this will transitively pull in a lot of our build-time dependencies, resulting in bigger client-side bundle size. To avoid this, we recommend using a tool like babel-plugin-preval to generate a static version of your configuration at build-time.

​TypeScript 类型

¥TypeScript types

我们为 tailwind.config.js 文件提供了第一方 TypeScript 类型，它为你提供了各种有用的 IDE 支持，并使更改配置变得容易得多，而无需参考文档。

¥We ship first-party TypeScript types for the tailwind.config.js file which give you all sorts of useful IDE support, and makes it a lot easier to make changes to your configuration without referencing the documentation quite as much.

使用 Tailwind CLI 生成的配置文件默认包含必要的类型注释，但要手动配置 TypeScript 类型，只需在配置对象上方添加类型注释：

¥Configuration files generated with Tailwind CLI include the necessary type annotation by default, but to configure TypeScript types manually, just add the type annotation above your configuration object:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}