Tailwind CSS home page
  1. Upgrade Guide

Tailwind CSS v3.0是对框架的一次重大更新，它使用了一个全新的内部引擎，因此包含了一些突破性的更改。

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

要了解更多关于Tailwind CSS v3.0的新功能，请阅读我们博客上的[Tailwind CSS v3.0公告]（/blog/tailwindcss-v3）。

升级程序包

使用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]（/docs/installation），而不是将Tailwind作为PostCSS插件安装。

如果你在自定义CSS中使用嵌套（与PostCSS嵌套插件结合使用），你还应该在PostCSS配置中[配置Tailwind CSS/nesting插件]（/docs/using with preprocessors#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

播放CDN

对于Tailwind CSS v3.0，我们过去提供的基于CSS的CDN构建已被新的[Play CDN]（/docs/installing/blay-CDN）所取代，这使您无需构建步骤即可在浏览器中完全使用新引擎。

要尝试一下，在你的<head>中抛出这个<script>标签：

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

我们在3月份宣布的新[Just in Time engine]（/blog/Just in Time，下一代顺风css）已经取代了顺风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: {
    // ...
  }
  // ...
}

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

由于我们不再在幕后使用PurgeCSS，一些高级清除选项已经发生了变化。有关高级选项的更多信息，请参阅新的[内容配置]（/docs/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文件中删除variables部分：

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

更换 @variants with @layer

由于默认情况下所有变体都已启用，因此您不再需要使用以下命令为自定义CSS显式启用这些变体 @variants 或者 @responsive 指令。

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

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

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

有关更多信息，请参阅[使用CSS和@layer添加自定义样式]（/docs/addy custom styles#使用CSS和layer）的文档。

自动转换和过滤

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

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

虽然将它们留在HTML中没有坏处，但可以安全地删除它们——只有一个例外。如果你依赖“transform”来创建新的堆叠上下文，你可能想离开它，否则你可能会遇到z顺序问题。或者，用“相对”或“隔离”替换它，以强制创建新的堆栈上下文。

新的不透明度修改器语法

新发动机推出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 Defaultv2 Extended
greenemerald
yellowamber
purpleviolet

在v3.0中，这些颜色默认使用其扩展名称，因此以前的“bg-green-500”现在是“bg-emerald-500”，“bg-grreen-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 Defaultv2 Extendedv3 Unified
N/AblueGrayslate
graycoolGraygray
N/Agrayzinc
N/AtrueGrayneutral
N/AwarmGraystone

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

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”用于“textoverflow:click”是一个非常糟糕的主意。

为了避免命名冲突，我们将“overflow clip”重命名为“text clip”，并将“overlow省略号”更名为“text省略号”：

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

这极不可能影响任何人，因为“文本剪辑”的用例很少，而且它只是为了完成而被包含在内。

柔性增长/收缩

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

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

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

outline黑色/白色

由于浏览器在渲染轮廓时终于开始考虑边框半径，我们为“轮廓样式”、“轮廓颜色”、“大纲宽度”和“轮廓偏移”属性添加了单独的实用程序。

这意味着“白色轮廓”和“黑色轮廓”现在只设置轮廓_color_，而在v2中，它们设置颜色、宽度、样式和偏移。

如果你在项目中使用“白色轮廓”或“黑色轮廓”，你可以通过在项目中添加以下自定义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">

coronation克隆/切片

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

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

在[排序堆叠修改器]（/docs/hover focus和其他状态#ordering stack modifier）文档中了解更多信息。

使用调色板填充和笔划

现在默认情况下，fill-*和stroke-*实用程序反映了您的theme.colors键。如果你没有自定义你的调色板，这不是一个突破性的变化，但如果你有，如果你没有在自己的自定义调色板中包含“当前”，那么“填充当前”和“笔划当前”类可能无法工作。

将“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的全局基础样式，而不会影响依赖于添加自己的基础样式才能正常运行的实用程序。

屏幕层已重命名

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

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

我认为你在办公桌前工作时更有可能被鲨鱼袭击，而不是受到这种变化的影响。