升级指南

将您的 Tailwind CSS 项目从 v2 升级到 v3。

Tailwind CSS v3.0 是该框架的重大更新，具有全新的内部引擎，因此包含了一些破坏性变化。

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

要了解有关 Tailwind CSS v3.0 的最新信息，请阅读我们博客上的 Tailwind CSS v3.0 公告。

升级软件包

使用 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 配置中配置 tailwindcss/nesting 插件，以确保与 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

Play CDN

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

要试一试，请在您的 <head> 中放置这个 <script> 标签：

html

<!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 引擎

我们在三月宣布的新的即时引擎已经取代了 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: {
    // ...
  }
  // ...
}

移除暗黑模式配置

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

tailwind.config.js

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

如果当前设置为 false ，您也可以安全地移除此密钥。

tailwind.config.js

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

移除变体配置

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

tailwind.config.js

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

用 @layer 替换 @variants

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

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

css

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

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

请查看有关使用 CSS 和 @layer 添加自定义样式的文档以获取更多信息。

自动转换和过滤器

在 Tailwind CSS v3.0 中，transform 和 filter 实用程序（如 scale-50 和 brightness-75 ）将自动生效，无需添加 transform 、 filter 或 backdrop-filter 类。

html

<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 替换它以强制创建新的堆叠上下文。

新的不透明度修改器语法

新引擎引入了一种改变颜色透明度的新语法，我们建议从像 bg-opacity-{value} 这样的实用程序迁移到这种语法。

html

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

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

html

<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/ellipsis

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

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

html

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

这几乎不太可能影响任何人，因为 text-clip 的使用情况非常少，它只是为了完整性而包含在内。

flex-grow/shrink

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

html

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

旧的类名仍然可以使用，但建议您更新为新的类名。

outline-black/white

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

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

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

css

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

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

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

html

<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 实用程序混淆。

html

<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 ）组合使用，您需要调整修饰符的顺序：

html

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

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

使用颜色调色板填充和描边

默认情况下， fill-{color} 和 stroke-{color} 实用程序现在会镜像您的 theme.colors 键。如果您尚未自定义颜色调色板，则这不会造成破坏性变化，但如果您已经自定义了颜色调色板，则如果您的自定义颜色调色板中没有包含 current ，那么 fill-current 和 stroke-current 类可能无法正常工作。

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

tailwind.config.js

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

负值已移除

在像 -mx-4 这样的实用程序中，否定前缀现在是 Tailwind 的一流特性，而不是由您的主题驱动的东西，因此您可以在支持负值的任何实用程序前面添加 - ，它将正常工作。

默认主题中已删除负值，因此如果您在 CSS 中引用它们使用 theme() ，编译时将会出现错误。

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

css

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

基础层必须存在

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

如果您之前通过不包括此指令来禁用 Tailwind 的基本样式，您应该将其添加回来，并在您的配置中禁用 preflight 。

main.csstailwind.config.js

css

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

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

这将禁用 Tailwind 的全局基础样式，而不影响依赖添加自己基础样式以正确运行的实用程序。

屏幕层已重命名

该 @tailwind screens 层已更名为 @tailwind variants ：

main.css

css

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

我认为在你工作时被鲨鱼攻击的可能性比受到这种改变的影响要大得多。

升级指南 ​

升级软件包 ​

官方插件 ​

Play CDN ​

迁移到 JIT 引擎 ​

配置内容来源 ​

移除暗黑模式配置 ​

移除变体配置 ​

用 @layer 替换 @variants ​

自动转换和过滤器 ​

新的不透明度修改器语法 ​

颜色调色板变化 ​

移除颜色别名 ​

重新命名的灰度级别 ​

类名变化 ​

overflow-clip/ellipsis ​

flex-grow/shrink ​

outline-black/white ​

decoration-clone/slice ​

其他小的改动 ​

分隔符不能是破折号 ​

前缀不能是一个函数 ​

文件修改器顺序已颠倒 ​

使用颜色调色板填充和描边 ​

负值已移除 ​

基础层必须存在 ​

屏幕层已重命名 ​

升级指南

升级软件包

官方插件

Play CDN

迁移到 JIT 引擎

配置内容来源

移除暗黑模式配置

移除变体配置

用 @layer 替换 @variants

自动转换和过滤器

新的不透明度修改器语法

颜色调色板变化

移除颜色别名

重新命名的灰度级别

类名变化

overflow-clip/ellipsis

flex-grow/shrink

outline-black/white

decoration-clone/slice

其他小的改动

分隔符不能是破折号

前缀不能是一个函数

文件修改器顺序已颠倒

使用颜色调色板填充和描边

负值已移除

基础层必须存在

屏幕层已重命名