升级指南 - Tailwind CSS 中文网

Tailwind CSS v3.0 是对该框架的重大更新，具有全新的内部引擎，因此包含少量重大更改。

¥Tailwind CSS v3.0 is a major update to the framework with a brand new internal engine and as such includes a small number of breaking changes.

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

¥We take stability very seriously and have worked hard to make any breaking changes as painless as possible. For most projects, upgrading to Tailwind CSS v3.0 should take less than 30 minutes.

https://www.youtube.com/embed/waoOK5s9ypc

要详细了解 Tailwind CSS v3.0 中的新功能，请阅读我们博客上的 Tailwind CSS v3.0 公告。

¥To learn more about what’s new in Tailwind CSS v3.0, read the Tailwind CSS v3.0 announcement on our blog.

升级包

¥Upgrade packages

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

¥Update Tailwind, as well as PostCSS and autoprefixer, using npm:

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

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

¥Note that Tailwind CSS v3.0 requires PostCSS 8, and no longer supports PostCSS 7. If you can’t upgrade to PostCSS 8, we recommend using Tailwind CLI instead of installing Tailwind as a PostCSS plugin.

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

¥If you are using nesting in your custom CSS (in combination with a PostCSS nesting plugin), you should also configure the tailwindcss/nesting plugin in your PostCSS configuration to ensure compatibility with Tailwind CSS v3.0.

官方插件

¥Official plugins

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

¥All of our first-party plugins have been updated for compatibility with v3.0.

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

¥If you’re using any of our plugins, make sure to update them all to the latest version at the same time to avoid version constraint errors.

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

体验 CDN

¥Play CDN

对于 Tailwind CSS v3.0，我们过去提供的基于 CSS 的 CDN 构建已被新的体验 CDN 取代，它让你无需构建步骤即可在浏览器中获得新引擎的全部功能。

¥For Tailwind CSS v3.0, the CSS-based CDN build we’ve offered in the past has been replaced by the new Play CDN, which gives you the full power of the new engine right in the browser with no build step.

要尝试一下，请将此 <script> 标签放入你的 <head> 中：

¥To try it out, throw this <script> tag in your <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 构建是生产中更好的选择。

¥The Play CDN is designed for development purposes only — compiling your own static CSS build is a much better choice in production.

迁移到 JIT 引擎

¥Migrating to the JIT engine

我们在 3 月份宣布的新即时引擎已经取代了 Tailwind CSS v3.0 中的经典引擎。

¥The new Just-in-Time engine we announced in March has replaced the classic engine in Tailwind CSS v3.0.

新引擎会按需生成你的项目所需的样式，并且可能需要对你的项目进行一些小的更改，具体取决于你如何配置 Tailwind。

¥The new engine generates the styles you need for your project on-demand, and might necessitate some small changes to your project depending on how you have Tailwind configured.

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

¥If you were already opting in to mode: 'jit' in Tailwind CSS v2.x, you can safely remove that from your configuration in v3.0:

tailwind.config.js

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

配置内容源

¥Configure content sources

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

¥Since Tailwind no longer uses PurgeCSS under the hood, we’ve renamed the purge option to content to better reflect what it’s for:

tailwind.config.js

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

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

¥If you weren’t already using the purge option in your project, it’s crucial that you configure your template paths now or your compiled CSS will be empty.

由于我们不再在后台使用 PurgeCSS，一些高级清除选项已经更改。有关高级选项的更多信息，请参阅新的内容配置文档。

¥Since we’re not using PurgeCSS under the hood anymore, some of the advanced purge options have changed. See the new content configuration documentation for more information on advanced options.

删除夜间模式配置

¥Remove dark mode configuration

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

¥The dark mode feature is now enabled using the media strategy by default, so you can remove this key entirely from your tailwind.config.js file, unless you’re using the class strategy.

tailwind.config.js

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

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

¥You can also safely remove this key if it’s currently set to false:

tailwind.config.js

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

删除变体配置

¥Remove variant configuration

在 Tailwind CSS v3.0 中，默认情况下每个变体都自动可用于每个工具，因此你可以从 tailwind.config.js 文件中删除 variants 部分：

¥In Tailwind CSS v3.0, every variant is automatically available for every utility by default, so you can remove the variants section from your tailwind.config.js file:

tailwind.config.js

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

使用 @layer 替换 @variants

¥Replace @variants with @layer

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

¥Since all variants are now enabled by default, you no longer need to explicitly enable these for custom CSS using the @variants or @responsive directives.

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

¥Instead, add any custom CSS to appropriate “layer” using the @layer directive:

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

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

¥Any custom CSS added to one of Tailwind’s layers will automatically support variants.

有关详细信息，请参阅使用 CSS 和 @layer 添加自定义样式上的文档。

¥See the documentation on adding custom styles using CSS and @layer for more information.

自动转换和过滤

¥Automatic transforms and filters

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

¥In Tailwind CSS v3.0, transform and filter utilities like scale-50 and brightness-75 will automatically take effect without needing to add the transform, filter, or backdrop-filter classes:

<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 以强制使用新的堆栈上下文。

¥While there’s no harm in leaving them in your HTML, they can safely be removed — with one exception. If you’re relying on transform to create a new stacking context, you may want to leave it, otherwise you may run into z-order issues. Alternatively, replace it with relative or isolate to force a new stacking context.

新的透明度修饰符语法

¥New opacity modifier syntax

新引擎引入了新语法，用于更改我们建议从 bg-opacity-* 等工具迁移到的颜色工具的透明度：

¥The new engine introduces a new syntax for changing the opacity of color utilities that we recommend migrating to from utilities like bg-opacity-*:

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

旧方法在所有情况下仍然有效，除了使用具有默认 border 类的 border-opacity-* 工具时 - 在 v3 中，你需要显式指定边框颜色：

¥The old approach still works in all cases except when using a border-opacity-* utility with the default border class — in v3 you’ll need to explicitly specify your border color:

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

其他所有情况的行为都相同，因此除了该更改之外，你的项目将完全像以前一样工作。不过，我们确实建议继续使用新语法，并计划在 v4 中默认禁用 border-opacity-* 和 bg-opacity-* 等工具，但你仍然可以在需要时启用它们。

¥Every other situation behaves the same, so aside from that change your projects will work exactly as they did before. We do recommend using the new syntax going forward though, and plan to disable utilities like border-opacity-* and bg-opacity-* by default in v4, though you will still be able to enable them if needed.

这种新语法适用于所有颜色工具，甚至是过去无法更改透明度的工具，如 from-red-500/75。

¥This new syntax works for all color utilities, even utilities that didn’t have any way to change the opacity in the past like from-red-500/75.

调色板变化

¥Color palette changes

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

¥Tailwind CSS v3.0 now includes every color from the extended color palette by default, including previously disabled colors like cyan, rose, fuchsia, and lime, and all five variations of gray.

删除了颜色别名

¥Removed color aliases

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

¥In v2.0, several of the default colors were actually aliases for the extended colors:

v2 默认	v2 扩展
`green`	`emerald`
`yellow`	`amber`
`purple`	`violet`

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

¥In v3.0, these colors use their extended names by default, so what was previously bg-green-500 is now bg-emerald-500, and bg-green-500 now refers to the green from the extended palette.

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

¥If you’re using these colors in your project, the simplest way to upgrade is to alias them back to their previous names in your tailwind.config.js file:

tailwind.config.js

const colors = require('tailwindcss/colors')

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

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

¥If you are already using a custom color palette, this change doesn’t impact you at all.

重命名灰度

¥Renamed gray scales

作为默认启用所有扩展颜色的一部分，我们为不同的灰色阴影提供了较短的单字名称，以使其更实用，并减少它们同时共存的尴尬。

¥As part of enabling all of the extended colors by default, we’ve given the different gray shades shorter single-word names to make them more practical to use and make it less awkward for them to co-exist at the same time.

v2 默认	v2 扩展	v3 统一
不适用	`blueGray`	`slate`
`gray`	`coolGray`	`gray`
不适用	`gray`	`zinc`
不适用	`trueGray`	`neutral`
不适用	`warmGray`	`stone`

如果你引用了任何扩展的灰色，你应该更新对新名称的引用，例如：

¥If you were referencing any of the extended grays, you should update your references to the new names, for example:

tailwind.config.js

const colors = require('tailwindcss/colors')

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

如果你没有引用扩展调色板中的任何灰色，则此更改根本不会影响你。

¥If you weren’t referencing any of the grays from the extended color palette, this change doesn’t impact you at all.

类名称变更

¥Class name changes

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

¥Some class names in Tailwind CSS v3.0 have changed to avoid naming collisions, improve the developer experience, or make it possible to support new features.

在可能的情况下，我们也保留了旧名称，因此其中许多更改都是非破坏性的，但我们鼓励你更新为新类名称。

¥Wherever possible we have preserved the old name as well so many of these changes are non-breaking, but you’re encouraged to update to the new class names.

overflow-clip/ellipsis

那些该死的浏览器开发者添加了一个真正的 overflow: clip 属性，所以现在将 overflow-clip 用于 text-overflow: clip 是一个非常糟糕的主意。

¥Those damn browser developers added a real overflow: clip property, so using overflow-clip for text-overflow: clip is a really bad idea now.

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

¥We’ve renamed overflow-clip to text-clip, and renamed overflow-ellipsis to text-ellipsis to avoid the naming collision:

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

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

¥This is extremely unlikely to affect anyone, as there are very few use-cases for text-clip and it’s only really included for the sake of completion.

flex-grow/shrink

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

¥We’ve added grow-* and shrink-* as aliases for flex-grow-* and flex-shrink-*:

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

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

¥The old class names will always work but you’re encouraged to update to the new ones.

outline-black/white

由于浏览器在渲染轮廓时终于开始考虑边框半径，我们为 outline-style、outline-color、outline-width 和 outline-offset 属性添加了单独的工具。

¥Since browsers are finally starting to respect border radius when rendering outlines, we’ve added separate utilities for the outline-style, outline-color, outline-width and outline-offset properties.

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

¥This means that outline-white and outline-black now only set the outline color, whereas in v2 they set the color, width, style, and offset.

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

¥If you are using outline-white or outline-black in your project, you can bring back the old styles by adding the following custom CSS to your project:

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

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

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

¥Alternatively, you can update any usage of them in your CSS with the following classes:

<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">

decoration-clone/slice

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

¥We’ve added box-decoration-clone and box-decoration-slice as aliases for decoration-clone and decoration-slice to avoid confusion with all of the new text-decoration utilities that use the decoration- namespace:

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

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

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

¥The old class names will always work but you’re encouraged to update to the new ones.

其他小改动

¥Other minor changes

Tailwind CSS v3.0 需要一些其他小的重大更改，这些更改不太可能影响很多人，但已在此处捕获。

¥Tailwind CSS v3.0 necessitates a couple of other small breaking changes that are unlikely to affect many people, but have been captured here.

分隔符不能是破折号

¥Separator cannot be a dash

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

¥The dash (-) character cannot be used as a custom separator in v3.0 because of a parsing ambiguity it introduces in the engine.

你必须切换到另一个角色，比如 _：

¥You’ll have to switch to another character like _ instead:

tailwind.config.js

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

前缀不能是函数

¥Prefix cannot be a function

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

¥Prior to Tailwind CSS v3.0, it was possible to define your class prefix as a function:

tailwind.config.js

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

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

¥This isn’t possible in the new engine and we’ve had to remove support for this feature.

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

¥Instead, use a static prefix that is the same for every class Tailwind generates:

tailwind.config.js

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

文件修饰符顺序颠倒

¥File modifier order reversed

自 v3.0.0-alpha.2 引入 file 修饰符以来的超级微小变化 - 如果你将其与 hover 或 focus 等其他修饰符组合，则需要翻转修饰符顺序：

¥Super minor change since v3.0.0-alpha.2 where the file modifier was introduced — if you were combining it with other modifiers like hover or focus, you’ll need to flip the modifier order:

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

在排序堆叠修饰符文档中了解更多信息。

¥Learn more in the ordering stacked modifiers documentation.

填充和描边使用调色板

¥Fill and stroke use color palette

fill-* 和 stroke-* 工具现在默认镜像你的 theme.colors 密钥。如果你没有自定义调色板，这不是重大更改，但如果你自定义了调色板，那么如果你没有在自己的自定义调色板中包含 current，则 fill-current 和 stroke-current 类可能无法工作。

¥The fill-* and stroke-* utilities mirror your theme.colors key by default now. This isn’t a breaking change if you haven’t customized your color palette, but if you have, the fill-current and stroke-current classes may not work if you don’t have current included in your own custom color palette.

将 current 添加到你的自定义调色板以解决此问题：

¥Add current to your custom color palette to resolve this:

tailwind.config.js

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

删除负值

¥Negative values removed

像 -mx-4 这样的工具中的负前缀现在是 Tailwind 中的一流功能，而不是由主题驱动的功能，因此你可以在任何支持负值的工具前面添加 - 并且它会正常工作。

¥The negative prefix in utilities like -mx-4 is a first class feature in Tailwind now, rather than something driven by your theme, so you can add - in front of any utility that support negative values and it will just work.

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

¥The negative values have been removed from the default theme, so if you were referencing them with theme(), you will see an error when trying to compile your CSS.

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

¥Use the calc() function to update any affected code:

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

基础层必须存在

¥Base layer must be present

在 Tailwind CSS v3.0 中，必须存在 @tailwind base 指令才能使转换、过滤和阴影等工具按预期工作。

¥In Tailwind CSS v3.0, the @tailwind base directive must be present for utilities like transforms, filters, and shadows to work as expected.

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

¥If you were previously disabling Tailwind’s base styles by not including this directive, you should add it back and disable preflight in your corePlugins configuration instead:

main.css

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

tailwind.config.js

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

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

¥This will disable Tailwind’s global base styles without affecting utilities that rely on adding their own base styles to function correctly.

屏幕层已重命名

¥Screens layer has been renamed

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

¥The @tailwind screens layer has been renamed to @tailwind variants:

main.css

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

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

¥I think you are more likely to be attacked by a shark while working at your desk than you are to be affected by this change.

目录