升级指南 - 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.

想了解 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 构建已经被新的 Play 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.

要试用它，请在你的 <head> 中添加这个 <script> 标签：

🌐 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)

我们在三月份宣布的全新即时引擎已经在 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 添加到适当的“层”中：

🌐 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 工具类将会自动生效，而无需添加 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 键。如果你没有自定义调色板，这不会造成破坏性变化，但如果你有自定义，fill-current 和 stroke-current 类可能无法使用，除非你在自己的自定义调色板中包含了 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.

目录