升级指南 - Tailwind CSS

Tailwind CSS v3.0 是该框架的一次重大更新，它采用了全新的内部引擎，因此包含少量重大变化。

我们非常重视稳定性，并努力使任何重大更改尽可能轻松。对于大多数项目，升级到 Tailwind CSS v3.0 应该只需不到 30 分钟。

要了解有关 Tailwind CSS v3.0 中的新功能的更多信息，请阅读我们博客上的 Tailwind CSS v3.0 announcement。

升级包

使用 npm 更新 Tailwind 以及 PostCSS 和 autoprefixer：

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

请注意，Tailwind CSS v3.0 需要 PostCSS 8，不再支持 PostCSS 7。如果您无法升级到 PostCSS 8，我们建议使用 Tailwind CLI，而不是将 Tailwind 安装为 PostCSS 插件。

如果您在自定义 CSS 中使用嵌套（与 PostCSS 嵌套插件结合使用），您还应该在 PostCSS 配置中使用 configure the tailwindcss/nesting plugin 以确保与 Tailwind CSS v3.0 兼容。

官方插件

我们所有的第一方插件都已更新，以兼容 v3.0。

如果您正在使用我们的任何插件，请确保同时将它们全部更新到最新版本，以避免版本限制错误。

npm install -D tailwindcss@latest \
  @tailwindcss/typography@latest \
  @tailwindcss/forms@latest \
  @tailwindcss/aspect-ratio@latest \
  @tailwindcss/line-clamp@latest \
  postcss@latest \
  autoprefixer@latest

播放 CDN

对于 Tailwind CSS v3.0，我们过去提供的基于 CSS 的 CDN 构建已被新的 Play CDN 取代，它使您无需构建步骤即可在浏览器中充分利用新引擎的全部功能。

为了尝试一下，请将此 <script> 标签放入您的 <head> 中：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <script src="https://cdn.tailwindcss.com"></script>
  </head>
  <body>
    <!-- -->
  </body>
</html>

Play CDN 仅用于开发目的 - 在生产中编译自己的静态 CSS 构建是更好的选择。

迁移到 JIT 引擎

我们在三月份宣布的全新 Just-in-Time engine 已经取代了 Tailwind CSS v3.0 中的经典引擎。

新引擎会根据需要生成项目所需的样式，并且可能需要根据 Tailwind 的配置方式对项目进行一些小的更改。

如果您已经在 Tailwind CSS v2.x 中选择加入 mode: 'jit'，则可以安全地从 v3.0 中的配置中删除它：

tailwind.config.js

module.exports = {
  mode: 'jit',
  // ...
}

配置内容来源

由于 Tailwind 不再在后台使用 PurgeCSS，我们已将 purge 选项重命名为 content，以更好地反映其用途：

tailwind.config.js

module.exports = {
  purge: [
  content: [
    // Example content paths...
    './public/**/*.html',
    './src/**/*.{js,jsx,ts,tsx,vue}',
  ],
  theme: {
    // ...
  }
  // ...
}

如果您尚未在项目中使用 purge 选项，那么现在配置模板路径至关重要，否则编译的 CSS 将为空。

由于我们不再使用 PurgeCSS，一些高级清除选项已发生改变。有关高级选项的更多信息，请参阅新的 content configuration 文档。

删除暗黑模式配置

现在默认使用 media 策略启用暗模式功能，因此您可以从 tailwind.config.js 文件中完全删除此键，除非您使用 class 策略。

tailwind.config.js

module.exports = {
  darkMode: 'media',
  // ...
}

如果此键当前设置为 false，您也可以安全地删除它：

tailwind.config.js

module.exports = {
  darkMode: false,
  // ...
}

删除变体配置

在 Tailwind CSS v3.0 中，每个变体默认自动适用于每个实用程序，因此您可以从 tailwind.config.js 文件中删除 variants 部分：

tailwind.config.js

module.exports = {
  // ...
  variants: {
    extend: {
      padding: ['hover'],
    }
  },
}

将 @variants 替换为 @layer

由于现在所有变体都默认启用，因此您不再需要使用 @variants 或 @responsive 指令为自定义 CSS 明确启用这些变体。

相反，使用 @layer 指令将任何自定义 CSS 添加到适当的层：

 @variants hover, focus {
 @layer utilities {
   .content-auto {
     content-visibility: auto;
   }
 }

添加到 Tailwind 图层之一的任何自定义 CSS 都将自动支持变体。

请参阅 adding custom styles using CSS and @layer 的文档以了解更多信息。

自动转换和过滤

在 Tailwind CSS v3.0 中，scale-50 和 brightness-75 等转换和过滤实用程序将自动生效，而无需添加 transform、filter 或 backdrop-filter 类：

<div class="transform scale-50 filter grayscale backdrop-filter backdrop-blur-sm">
<div class="scale-50 grayscale backdrop-blur-sm">

虽然将它们保留在 HTML 中并没有什么坏处，但可以安全地删除它们 — 但有一个例外。如果您依赖 transform 来创建新的堆叠上下文，则可能需要保留它，否则可能会遇到 z 顺序问题。或者，将其替换为 relative 或 isolate 以强制使用新的堆叠上下文。

新的不透明度修饰符语法

新引擎引入了 a new syntax 来更改颜色实用程序的不透明度，我们建议从 bg-opacity-* 等实用程序迁移到该实用程序：

<div class="bg-black bg-opacity-25">
<div class="bg-black/25">

旧方法在所有情况下仍然有效，除非使用带有默认 border 类的 border-opacity-* 实用程序 - 在 v3 中，您需要明确指定边框颜色：

<div class="border border-opacity-25">
<div class="border border-gray-200/25">

其他所有情况都一样，因此除了这一变化之外，您的项目将与以前完全一样。但我们确实建议今后使用新语法，并计划在 v4 中默认禁用 border-opacity-* 和 bg-opacity-* 等实用程序，但您仍然可以根据需要启用它们。

这种新语法适用于所有颜色实用程序，甚至适用于过去无法改变不透明度的实用程序，如from-red-500/75。

调色板变化

Tailwind CSS v3.0 现在默认包含扩展调色板中的每种颜色，包括以前禁用的颜色，如青色、玫瑰色、紫红色和柠檬绿，以及所有五种灰色。

删除颜色别名

在 v2.0 中，几种默认颜色实际上是扩展颜色的别名：

v2 Default	v2 Extended
`green`	`emerald`
`yellow`	`amber`
`purple`	`violet`

在 v3.0 中，这些颜色默认使用其扩展名称，因此之前的 bg-green-500 现在是 bg-emerald-500，而 bg-green-500 现在指的是扩展调色板中的绿色。

如果您在项目中使用这些颜色，最简单的升级方法是在 tailwind.config.js 文件中将它们重新命名为以前的名称：

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        green: colors.emerald,
        yellow: colors.amber,
        purple: colors.violet,
      }
    },
  },
  // ...
}

如果您已经在使用自定义调色板，则此更改不会对您产生任何影响。

重命名灰度

作为默认启用所有扩展颜色的一部分，我们为不同的灰色色调赋予了更短的单词名称，以使它们更实用，并使它们同时共存时不那么尴尬。

v2 Default	v2 Extended	v3 Unified
N/A	`blueGray`	`slate`
`gray`	`coolGray`	`gray`
N/A	`gray`	`zinc`
N/A	`trueGray`	`neutral`
N/A	`warmGray`	`stone`

如果您引用了任何扩展的灰色，则应该将您的引用更新为新名称，例如：

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        gray: colors.trueGray,
        gray: colors.neutral,
      }
    },
  },
  // ...
}

如果您没有引用扩展调色板中的任何灰色，则此更改不会对您产生任何影响。

班级名称变更

Tailwind CSS v3.0 中的某些类名已更改，以避免命名冲突、改善开发人员体验或支持新功能。

只要有可能，我们就会保留旧名称，因此其中许多更改都不会造成重大影响，但我们鼓励您更新到新的类名。

溢出剪辑/省略号

那些该死的浏览器开发人员添加了一个真正的 overflow: clip 属性，因此现在使用 overflow-clip 来表示 text-overflow: clip 是一个非常糟糕的主意。

我们将 overflow-clip 重命名为 text-clip，并将 overflow-ellipsis 重命名为 text-ellipsis，以避免命名冲突：

<div class="overflow-clip overflow-ellipsis">
<div class="text-clip text-ellipsis">

这极不可能影响任何人，因为 text-clip 的用例很少，而且它只是为了完成而包含的。

弹性增长/收缩

我们已添加 grow-* 和 shrink-* 作为 flex-grow-* 和 flex-shrink-* 的别名：

<div class="flex-grow-0 flex-shrink">
<div class="grow-0 shrink">

旧的类名将始终有效，但我们鼓励您更新到新的类名。

轮廓-黑色/白色

由于浏览器在渲染轮廓时最终开始尊重边框半径，我们为 outline-style、outline-color、outline-width 和 outline-offset 属性添加了单独的实用程序。

这意味着 outline-white 和 outline-black 现在仅设置轮廓颜色，而在 v2 中，它们设置颜色、宽度、样式和偏移量。

如果您在项目中使用 outline-white 或 outline-black，则可以通过在项目中添加以下自定义 CSS 来恢复旧样式：

@layer utilities {
  .outline-black {
    outline: 2px dotted black;
    outline-offset: 2px;
  }

  .outline-white {
    outline: 2px dotted white;
    outline-offset: 2px;
  }
}

或者，你可以使用以下类来更新 CSS 中对它们的任何使用：

<div class="outline-black">
<div class="outline-black outline-2 outline-dotted outline-offset-2">

<div class="outline-white">
<div class="outline-white outline-2 outline-dotted outline-offset-2">

装饰-克隆/切片

我们添加了 box-decoration-clone 和 box-decoration-slice 作为 decoration-clone 和 decoration-slice 的别名，以避免与使用 decoration- 命名空间的所有新 text-decoration 实用程序混淆：

<div class="decoration-clone"></div>
<div class="box-decoration-clone"></div>

<div class="decoration-slice"></div>
<div class="box-decoration-slice"></div>

旧的类名将始终有效，但我们鼓励您更新到新的类名。

其他小改动

Tailwind CSS v3.0 需要进行一些其他小的重大改变，这些改变不太可能影响到很多人，但已在这里记录下来。

分隔符不能是破折号

破折号（-）字符不能在 v3.0 中用作自定义分隔符，因为它会在引擎中引入解析歧义。

您必须切换到另一个字符，例如 _ ：

tailwind.config.js

module.exports = {
  // ...
  separator: '-',
  separator: '_',
}

前缀不能是函数

在 Tailwind CSS v3.0 之前，可以将类前缀定义为函数：

tailwind.config.js

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

这在新引擎中是不可能的，因此我们不得不取消对该功能的支持。

相反，对 Tailwind 生成的每个类使用相同的静态前缀：

tailwind.config.js

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

文件修改器顺序已反转

自 v3.0.0-alpha.2 以来，引入了 file 修饰符，这是一个非常小的变化 - 如果将它与其他修饰符（如 hover 或 focus）结合使用，则需要翻转修饰符顺序：

<input class="file:hover:bg-blue-600 ...">
<input class="hover:file:bg-blue-600 ...">

在 ordering stacked modifiers 文档中了解更多信息。

填充和描边使用调色板

fill-* 和 stroke-* 实用程序现在默认镜像您的 theme.colors 键。如果您尚未自定义调色板，则这不是重大变化，但如果您已自定义调色板，并且您未在自己的自定义调色板中包含 current，则 fill-current 和 stroke-current 类可能无法工作。

将 current 添加到您的自定义调色板即可解决此问题：

tailwind.config.js

module.exports = {
  // ...
  theme: {
    colors: {
      current: 'currentColor',
      // ...
    }
  }
}

已删除负值

实用程序中的负前缀（例如 -mx-4）现在是 Tailwind 中的一流功能，而不是由主题驱动的功能，因此您可以在任何支持负值的实用程序前面添加 -，它就会正常工作。

负值已从默认主题中删除，因此如果您使用 theme() 引用它们，则在尝试编译 CSS 时会看到错误。

使用 calc() 函数更新任何受影响的代码：

.my-class {
  top: theme('top.-4')
  top: calc(theme('top.4') * -1)
}

必须存在基础层

在 Tailwind CSS v3.0 中，必须存在 @tailwind base 指令，变换、过滤器和阴影等实用程序才能按预期工作。

如果您之前未包含此指令而禁用了 Tailwind 的基本样式，则应将其添加回来并在 corePlugins 配置中禁用 preflight：

main.css

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

tailwind.config.js

module.exports = {
  // ...
  corePlugins: {
    preflight: false,
  },
}

这将禁用 Tailwind 的全局基本样式，而不会影响依赖添加自己的基本样式才能正常运行的实用程序。

屏幕层已重命名

@tailwind screens 层已重命名为 @tailwind variants：

main.css

 /* ... */
 @tailwind screens;
 @tailwind variants;

我认为你在办公桌前工作时被鲨鱼袭击的可能性比你受到这一变化的影响更大。

On this page