Tailwind CSS on GitHub

安装

学习如何安装Tailwind CSS并且运行项目

安装指南

相对其他框架或者工具,安装Tailwind CSS可能是一个略有不同的体验,我们把一些流行的框架安装教程都打包放在一起了。

上面的列表没有你常用的框架? 我们一直在做新的安装指南, 你也可以按照 把Tailwind CSS作为PostCSS插件安装 教程来安装一个插件,而不是直接安装Tailwind CSS框架。


把Tailwind CSS作为PostCSS插件安装

Tailwind CSS 需要 Node.js 12.13.0 或者更高版本。

对于大多数实际项目,我们建议安装Tailwind作为一个PostCSS插件。大多数现代框架已经在底层使用了PostCSS,而且很有可能你已经或正在使用其他的PostCSS插件,比如 autoprefixer.

如果你从未听说过PostCSS,或者想知道它与Sass等工具有何不同,请阅读使用PostCSS当做预处理器

如果这对你来说有点困难,你想尝试不用配置PostCSS的Tailwind,请阅读直接使用Tailwind CSS而不是PostCSS

通过npm安装Tailwind

对于大多数项目 (以及利用Tailwind的定制特性),你应该都想要使用npm来安装Tailwind CSS及其依赖。

npm install tailwindcss@latest postcss@latest autoprefixer@latest

由于Tailwind不会自动将供应商前缀 添加到它生成的CSS中,所以我们建议安装 autoprefixer 来解决这个问题,就像我们在上面的代码片段中显示的那样。

如果你将Tailwind与一个依赖于旧版本PostCSS的工具集成,你可能会看到这样的错误:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

这种情况, 你应该 安装PostCSS 7兼容版

添加Tailwind到PostCSS插件

添加 tailwindcssautoprefixer 到你的PostCSS配置文件。它大部分情况在你的项目根目录,名字叫 postcss.config.js,也可能是.postcssrc,或者定义在你的package.json文件里面的postcss字段里面。

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

如果你不确定你使用的工具的PostCSS插件配置在哪里,你可以参考这些工具的文档,查看应该放在哪里。 直接Google搜索"configure postcss {my tool}"也可以很快得到答案。

如果你有在使用其他的PostCSS插件,你最好阅读一下使用PostCSS作为你的预处理器了解更多细节,以便更好的与Tailwind CSS配合。

创建配置文件

如果你想自动生成配置文件,你可以试试Tailwind CLI。 在你安装好tailwindcss依赖之后,运行:

npx tailwindcss init

上面的命令会生成一个简化版的tailwind.config.js文件到你的项目根目录:

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

配置文档查看更多配置项。

在CSS中引入Tailwind

创建一个css文件, 并通过@tailwind指令注入Tailwind的basecomponentsutilities 样式:

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

Tailwind会根据你的配置信息,生成对应的样式代码,然后替换这几个指令。

如果你使用postcss-import 或者Webpacker for Rails), 直接使用imports,而不是@tailwind,避免在导入其他的文件时候出现的问题:

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

如果你使用的是React/Vue这样的能在js里直接引入css的框架,你可以直接使用 tailwindcss/tailwind.css 而不需要常见一个css文件,因为已经有了这些指令:

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

构建你的CSS

如何构建项目取决于你使用的框架. 你的框架可能会使用命令npm run dev 去启动一个本地环境,并在后台编译你的CSS,你也可能直接运行你自己配置的webpack ,你也可能postcss-cli并且使用命名如:postcss styles.css -o compiled.css.

如果你已经非常熟悉PostCSS,你应该知道自己再做什么,如果不是,请参考请阅读你使用的框架文档

当打包正式环境的时候,确保配置了purge以删除未使用的css

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

读取我们关于生产的独立指南,了解更多 生产指南关于tree-shaking未使用的样式,已获得更好的性能。

如果你集成的Tailwind依赖于一个旧版本的PostCSS,你可能会看到下面的错误:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

这种情况,你需要 切换到PostCSS 7兼容性构建


直接使用Tailwind

Tailwind CSS requires Node.js 12.13.0 or higher.

对于简单的项目来说,你可以直接使用Tailwind CLI来生成你的CSS,而不需要配置PostCSS;如果不想使用Tailwind CLI,也可以安装Tailwind作为一个依赖。

使用npx命令去生成完整编译的Tailwind CSS文件:

npx tailwindcss-cli@latest build -o tailwind.css

这会生成一个叫做tailwind.css的CSS文件,它依赖于Tailwind的默认配置,并且会使用autoprefixer自动添加浏览器前缀。

现在你可以像一个普通的CSS文件一样把它引入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文件

如果你想自定义新的CSS或者Tailwind的默认样式,在你的资源文件夹创建一个CSS文件,使用@tailwind指令去引入Tailwind的basecomponents,以及 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

查看添加基础样式扩展组件,以及添加新的工具类 来了解如何自定义CSS到Tailwind。

自定义配置项

如果你想自定义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

如果你想把配置文件放到其他目录或者给它换一个名字,那么在使用生成命令的时候,需要添加-c参数:

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

通过配置文档来了解更多Tailwind配置项。

禁用Autoprefixer

Tailwind CLI 默认会使用Autoprefixer工具来生成必要的浏览器前缀。 如果你已经自行配置了Autoprefixer,可以在Tailwind CLI使用--no-autoprefixer来避免调用Autoprefixer两次。

npx tailwindcss-cli@latest build --no-autoprefixer -o tailwind.css

生产构建

当要构建生产环境的文件时,在命令行添加NODE_ENV=production

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

这样可以确保Tailwind会移除任何未使用的CSS, 查看生产构建优化来了解更多。


通过CDN引入Tailwind

在此之前,你必须明确,如果不把Tailwind整合到构建过程中,很多Tailwind CSS很棒的特性你都不能使用。

  • 你不能自定义Tailwind的默认样式
  • 你不能使用指令,比如 @apply@variants
  • 你不能启用其他的variants,比如group-focus
  • 你不能安装第三方插件
  • 你不能tree-shake未使用样式

为了更好的发挥Tailwind的特性,你真的需要把它作为PostCSS插件安装

为了快速制作一个demo,你可以通过CDN获取最新的文件:

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

注意一点,虽然CDN构建的文件很大(压缩版73kB, 未压缩300kB)但是这不能代表使用把Tailwind整合到构建过程中生成的文件大小

通过我们的最佳实践基本可以让生成的文件小于10kb。


HTML模板

为了让Tailwind的样式像预期的那样工作,你需要使用HTML5 doctype并包括响应视口元标签来正确处理所有设备上的响应样式。

<!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、vue-cli等这样的前端框架已经自动帮你做了这件事。


PostCSS 7兼容版

Tailwind CSS 2.0依赖PostCSS 8。因为PostCSS8 只推出几个月,很多生态系统中的工具都没有更新,这意味着你在安装和编译Tailwind的过程中,可能看到下面的错误:

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