安装 - Tailwind CSS 中文文档

集成指南

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

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

以 PostCSS 插件的形式安装 Tailwind CSS

对于大多数现实中的工程，我们建议作为一个 PostCSS 插件来安装 Tailwind。大多数的现代框架基本都默认使用了 PostCSS，您很可能已经使用或当前正在使用其它 PostCSS 插件，例如 autoprefixer.

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

如果您觉得这有些麻烦，并且想在不配置 PostCSS 的情况下尝试使用 Tailwind，请阅读有关在不依赖 PostCSS 使用 Tailwind 的说明。

通过 npm 安装 Tailwind

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

npm install tailwindcss@latest postcss@latest autoprefixer@latest

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

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

Error: PostCSS plugin tailwindcss requires PostCSS 8.

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

作为 PostCSS 插件来添加 Tailwind

将 tailwindcss 和 autoprefixer 添加到您的 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 兼容性版本。

不依赖 PostCSS 使用 Tailwind

对于简单的项目或只是体验一下 Tailwind，您可以使用 Tailwind CLI 工具生成 CSS，而无需配置 PostCSS 或甚至不需要安装 Tailwind 作为依赖项。

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

npx tailwindcss-cli@latest build -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>

使用自定义 CSS 文件

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

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

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

@tailwind utilities;

然后使用 npx tailwindcss build 构建 CSS 时，指定该文件的路径：

npx tailwindcss-cli@latest build ./src/tailwind.css -o ./dist/tailwind.css

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

自定义您的配置

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

npx tailwindcss-cli@latest init

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

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

这个文件会在使用 npx tailwindcss build 命令生成您的 CSS 文件时被自动读取：

npx tailwindcss-cli@latest build ./src/tailwind.css -o ./dist/tailwind.css

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

npx tailwindcss-cli@latest build ./src/tailwind.css -c ./.config/tailwind.config.js -o ./dist/tailwind.css

了解更多配置 Tailwind 文档。

为生产而构建

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

NODE_ENV=production npx tailwindcss-cli@latest build ./src/tailwind.css -o ./dist/tailwind.css

这将确保 Tailwind 删除所有未使用的 CSS 并最小化 CSS 文件以获得最佳性能。阅读我们有关优化生产的单独指南，以了解更多信息。

通过 CDN 来使用 Tailwind

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

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

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

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

请注意因为 CDN 文件很大 (72.4kB compressed, 2927.6kB 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.

为了弥合这个问题，直到每个人都进行了更新，我们还在 npm 的 compat 频道下发布了 PostCSS 7 兼容性版本。

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

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

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

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

npm uninstall tailwindcss @tailwindcss/postcss7-compat
npm install tailwindcss@latest postcss@latest autoprefixer@latest

安装