Just-in-Time: The Next Generation of Tailwind CSS
Tailwind CSS on GitHub

安装

学习如何在您的工程中使用 Tailwind CSS

Integration guides

Installing Tailwind CSS can be a slightly different process depending on what other frameworks/tools you’re using, so we’ve put together a bunch of guides that cover popular setups.

对于不同的框架/工具,安装 Tailwind CSS 是完全不同的过程,所以我们整理了一份常见安装的指南集合。

没有在列表中看到您的工具?我们一直在扩充新的指南,同时您也可以按照 以 PostCSS 插件的形式安装 Tailwind CSS 的文档来安装。


Installing Tailwind CSS as a PostCSS plugin

Tailwind CSS requires Node.js 12.13.0 or higher.

For most real-world projects, we recommend installing Tailwind as a PostCSS plugin. Most modern frameworks use PostCSS under the hood already, and there’s a good chance you’ve used or are currently using other PostCSS plugins like autoprefixer.

如果您从没有听说过 PostCSS,或者很想知道它与其它工具,如 Sass 的区别,请阅读我们的指南:将 PostCSS 用作预处理器

If this is a bit over your head and you’d like to try Tailwind without configuring PostCSS, read our instructions on using Tailwind CLI instead.

通过 npm 安装 Tailwind

对于大多数项目(并利用 Tailwind 的自定义功能),您需要通过 npm 安装 Tailwind 及其依赖项。

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

由于 Tailwind 不会自动添加浏览器引擎前缀到生成的 CSS 中,我们建议您安装 autoprefixer 去处理这个问题,就像上面的代码片段所展示的那样。

如果您将 Tailwind 与依赖于旧版本 PostCSS 的工具集成在一起,则可能会看到如下错误:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

在这种情况下,您应该安装 PostCSS 7 兼容性版本

作为 PostCSS 插件来添加 Tailwind

tailwindcssautoprefixer 添加到您的 PostCSS 配置中。 多数情况下,这是项目根目录下的 postcss.config.js 文件,但也可能是 .postcssrc 文件或是由 package.json 文件中的 postcss 键所指定。

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

如果您不太清楚如何在您正在使用的工具如何配置 PostCSS,则需要参考一下这些工具的文档。搜索 ”configure postcss {我的工具名字}” 也将很快为您提供答案。

如果您使用的是其他 PostCSS 插件,则应阅读有关将 PostCSS 用作预处理器的文档,以获取有关与 Tailwind 集成在一起的最佳实践的详细信息。

创建您的配置文件

如果您想要自定义您的 Tailwind 安装,可以使用 Tailwind CLI 工具生成一份配置文件,这个命令行工具已包含在了 tailwindcss 这个 npm 包里了。

npx tailwindcss init

这将会在您的工程根目录创建一个最小的 tailwind.config.js 文件。

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

配置文档中了解有关配置 Tailwind 的更多信息。

包含 Tailwind 到您的 CSS 中

如果您尚未创建一个 CSS 文件,请使用 @tailwind 指令注入 Tailwind 的基础 (base),组件 (components) 和功能 (utilities) 样式:

/* ./your-css-folder/styles.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind 将在构建时将这些指令替换为基于您配置的设计系统生成的所有样式。

如果您使用的是 postcss-import(或背后使用它的工具,例如 Webpacker for Rails),请使用我们的导入而不是 @tailwind 指令来避免在导入任何其他文件时出现问题:

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

如果您使用的是像 React 或 Vue 这样的 JavaScript 框架,支持直接将 CSS 文件导入到 JS 中,那么您也可以完全跳过创建 CSS 文件,而直接导入 tailwindcss / tailwind.css,而后者已经安装了所有这些指令:

// app.js
import "tailwindcss/tailwind.css"

生成您的 CSS

实际构建项目的方式将取决于您使用的工具。 您的框架可能包含诸如 npm run dev 之类的命令,以启动在后台编译 CSS 的开发服务器,您可能自己在运行 webpack,或者您正在使用 postcss-cli 并运行诸如 postcss styles.css -o compiled.css 之类的命令。

如果您已经熟悉 PostCSS,则可能知道您需要做什么,如果不熟悉,请参考所用工具的文档。

为生产而构建时,请确保配置清除 (purge) 选项以删除任何未使用类,这样生成的文件尺寸最小:

  // tailwind.config.js
  module.exports = {
+   purge: [
+     './src/**/*.html',
+     './src/**/*.js',
+   ],
    darkMode: false, // or 'media' or 'class'
    theme: {
      extend: {},
    },
    variants: {},
    plugins: [],
  }

阅读我们有关优化生产的单独指南,以了解有关 tree-shaking 优化未使用样式以获得最佳性能的更多信息。

如果您将 Tailwind 与依赖于较旧版本 PostCSS 的工具集成在一起,则在尝试构建 CSS 时可能会看到如下错误:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

在这种情况下,您应该切换到我们的 PostCSS 7 兼容性版本


Using Tailwind CLI

Tailwind CSS requires Node.js 12.13.0 or higher.

If you’d like to compile your CSS with Tailwind without integrating it directly into any sort of build tooling, you can use the Tailwind CLI tool to generate your CSS without configuring PostCSS or even installing Tailwind as a dependency if you don’t want to.

Use npx which is a tool that is automatically installed alongside npm to generate a fully compiled Tailwind CSS file: —> 对于简单的项目或只是体验一下 Tailwind,您可以使用 Tailwind CLI 工具生成 CSS,而无需配置 PostCSS 或甚至不需要安装 Tailwind 作为依赖项。

使用 npx 这个工具,它会与 npm 一起自动安装,以生成完全编译的 Tailwind CSS 文件:

npx tailwindcss -o tailwind.css

这将创建一个基于 Tailwind 的默认配置生成的名为 tailwind.css 的文件,并使用 autoprefixer 自动添加任何必需的浏览器前缀。

现在,您可以像其他样式表一样将此文件引入到 HTML 中:

<!doctype html>
<html>
<head>
  <!-- ... -->
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/tailwind.css" rel="stylesheet">
</head>
<body>
  <!-- ... -->
</body>
</html>

Watching for changes

You can use the --watch or -w flag to start a watch process and automatically rebuild your CSS any time you make any changes:

npx tailwindcss -o tailwind.css --watch

Using a custom CSS file

如果您想基于 Tailwind 生成的默认样式自定义任何 CSS ,通常情况下只需创建一个 CSS 文件,并使用 @tailwind 指令包含 Tailwind 的 basecomponentsutilities 样式:

/* ./src/tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .btn {
    @apply px-4 py-2 bg-blue-600 text-white rounded;
  }
}

Then include the path to that file when building your CSS:

npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

阅读有关添加基本样式提取组件以及添加新的功能类的文档,以了解有关在 Tailwind  基础上添加自定义 CSS 的更多信息。

自定义您的配置

如果您想自定义 Tailwind 生成的内容,请使用 Tailwind CLI 工具创建一个 tailwind.config.js 文件:

npx tailwindcss init

这将会在您工程的根目录生成一个最小版本的 tailwind.config.js 文件。

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

This file will automatically be read when building your CSS with Tailwind CLI:

npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

如果您想将配置文件保存在其他位置或使用其他名称,请在构建 CSS 时使用 -c 选项传递配置文件路径:

npx tailwindcss -i ./src/tailwind.css -c ./.config/tailwind.config.js -o ./dist/tailwind.css

了解更多配置 Tailwind 文档

Disabling Autoprefixer

By default, the Tailwind CLI tool will run your CSS through Autoprefixer to add any necessary vendor prefixes. If you already have Autoprefixer set up in your build pipeline somewhere further down the chain, you can disable it in the Tailwind CLI tool using the --no-autoprefixer flag to avoid running it twice:

npx tailwindcss --no-autoprefixer -o tailwind.css

Using a custom PostCSS configuration

If you’d like to use other PostCSS plugins alongside Tailwind, you can create a postcss.config.js file in your project root to add your extra plugins and Tailwind will include them if you use the --postcss flag when building your CSS:

npx tailwindcss --postcss -o tailwind.css
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-100vh-fix'),
  ]
}

By default, plugins are applied after Tailwind generates your CSS. If you have plugins that need to run before Tailwind, just include tailwindcss in your plugin list and Tailwind CLI will detect it and respect your custom plugin order:

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss'),
    require('postcss-100vh-fix'),
  ]
}

If you’d like to automatically generate a basic postcss.config.js file when creating your tailwind.config.js file, use the --postcss or -p flag when initializing your config file:

npx tailwindcss init --postcss

Building for production

为生产而构建时,在生成 CSS 时在命令行上设置 NODE_ENV = production

NODE_ENV=production npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

This will make sure Tailwind removes any unused CSS for best performance. Read our separate guide on optimizing for production to learn more.

You can also use the --minify flag to compress your CSS with cssnano:

NODE_ENV=production npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css --minify

通过 CDN 来使用 Tailwind

在使用 CDN 之前,请注意,如果没有将 Tailwind 集成到您的构建过程中,那么许多使 Tailwind CSS 强大的功能将不可用。

  • 您无法自定义 Tailwind 默认主题
  • 您不能使用任何 指令, 如: @apply@variants 等等
  • 您无法启用更多的变体,如: group-focus
  • 您无法下载第三方的插件
  • 您无法 tree-shake 未使用到的 Styles

To get the most out of Tailwind, you really should install it as a PostCSS plugin.

想要充分利用 Tailwind,您应该作为 PostCSS 插件安装 Tailwind

想要使用 Tailwind 进行快速演示,或者只是试一下框架,请通过 CDN 获取最新的默认配置:

<link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">

请注意因为 CDN 文件很大 (72.8kB compressed, 2936.0kB raw), 它并不代表您将 Tailwind 作为构建过程的一部分时生成的文件尺寸也是这么大.

遵循我们最佳实践的网站几乎总是压缩在10kb以下。


HTML 启动模板

为了使 Tailwind 的样式能够按预期工作,您将需要使用 HTML5 文档类型并包括响应式视口元标记以正确处理所有设备上的响应式样式。

<!doctype html>
<html>
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/path/to/tailwind.css" rel="stylesheet">
  <!-- ... -->
</head>
<body>
  <!-- ... -->
</body>
</html>

许多前端框架(如 Next.js,vue-cli 等)会在后台自动为您完成所有这些操作,因此,根据您要构建的内容,可能不需要进行设置。


PostCSS 7 兼容性版本

从 v2.0 版本开始,Tailwind CSS 依赖于 PostCSS 8。由于 PostCSS 8 才使用了几个月,因此生态系统中的许多其他工具尚未更新,这意味着在安装 Tailwind,并尝试编译 CSS 时,您可能会在终端中看到这样的错误:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

To help bridge the gap until everyone has updated, we also publish a PostCSS 7 compatibility build as @tailwindcss/postcss7-compat on npm.

如果遇到上述错误,请卸载 Tailwind 并使用兼容性版本重新安装:

npm uninstall tailwindcss postcss autoprefixer
npm install -D tailwindcss@npm:@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

兼容性版本在任何方面都与主版本相同,因此您不会错过任何功能或类似功能。

一旦您的其余工具添加了对 PostCSS 8 的支持,就可以通过使用 latest 标签重新安装 Tailwind 及其相关依赖项来取代兼容性构建:

npm uninstall tailwindcss
npm install -D tailwindcss@latest postcss@latest autoprefixer@latest