配置

因为 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 { /* ... */ }
}

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

.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. */

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

🌐 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)

将 important 设置为 true 在引入向元素添加内联样式的第三方 JS 库时可能会引发一些问题。在这种情况下，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: [],
}