升级指南

Tailwind CSS v4.0 是该框架的新主要版本，因此虽然我们非常努力地最小化重大变更，但一些更新是必要的。本指南概述了将项目从 v3 升级到 v4 所需的所有步骤。

Tailwind CSS v4.0 专为 Safari 16.4+、Chrome 111+ 和 Firefox 128+ 设计。 如果您需要支持较旧的浏览器，请继续使用 v3.4，直到您的浏览器支持要求发生变化。

使用升级工具

如果您想将项目从 v3 升级到 v4，可以使用我们的升级工具为您完成大部分繁重的工作：

$ npx @tailwindcss/upgrade

对于大多数项目，升级工具将自动化整个迁移过程，包括更新依赖项、将配置文件迁移为 CSS，以及处理模板文件的任何变更。

升级工具需要 Node.js 20 或更高版本，因此请确保在运行它之前更新您的环境。

我们建议在新分支中运行升级工具，然后仔细查看差异并在浏览器中测试您的项目，以确保所有变更看起来都是正确的。在复杂项目中，您可能需要手动调整一些内容，但无论如何，该工具将为您节省大量时间。

查看 v4 中的所有重大变更并充分了解变更内容也是一个好主意，以防升级工具未能捕获到您项目中需要更新的其他内容。

手动升级

使用 PostCSS

在 v3 中，tailwindcss 包是一个 PostCSS 插件，但在 v4 中，PostCSS 插件位于专用的 @tailwindcss/postcss 包中。

此外，在 v4 中，导入和供应商前缀现在为您自动处理，因此如果您的项目中有 postcss-import 和 autoprefixer，您可以将它们移除：

export default {  plugins: {    "postcss-import": {},    tailwindcss: {},    autoprefixer: {},    "@tailwindcss/postcss": {},  },};

使用 Vite

如果您使用的是 Vite，我们建议从 PostCSS 插件迁移到我们新的专用 Vite 插件，以获得更好的性能和最佳的开发者体验：

import { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({  plugins: [    tailwindcss(),  ],});

使用 Tailwind CLI

在 v4 中，Tailwind CLI 位于专用的 @tailwindcss/cli 包中。更新您的任何构建命令以使用新包：

npx tailwindcss -i input.css -o output.cssnpx @tailwindcss/cli -i input.css -o output.css

v3 的变更

以下是 Tailwind CSS v4.0 中所有重大变更的全面列表。

我们的升级工具将为您自动处理这些变更中的大部分，因此如果可以的话，我们强烈建议使用它。

浏览器要求

Tailwind CSS v4.0 专为现代浏览器设计，目标是 Safari 16.4、Chrome 111 和 Firefox 128。我们依赖现代 CSS 功能如 @property 和 color-mix() 来实现核心框架功能，Tailwind CSS v4.0 不能在较旧的浏览器中工作。

如果您需要支持较旧的浏览器，我们建议现在继续使用 v3.4。我们正在积极探索兼容模式，以帮助用户更早升级，我们希望在未来分享更多相关消息。

移除的 @tailwind 指令

在 v4 中，您使用常规的 CSS @import 语句导入 Tailwind，而不是使用您在 v3 中使用的 @tailwind 指令：

@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";

移除的已弃用工具类

我们已经移除了在 v3 中已弃用且多年未记录的任何工具类。以下是已移除内容及其现代替代方案的列表：

重命名的工具类

我们在 v4 中重命名了以下工具类，使它们更加一致和可预测：

重命名的轮廓工具类

现在 outline 工具类默认设置 outline-width: 1px，以与边框和环形工具类更加一致。此外，所有 outline-<number> 工具类默认将 outline-style 设置为 solid，无需与 outline 组合使用：

默认环形宽度变更

在 v3 中，ring 工具类添加了 3px 环形。我们在 v4 中将其更改为 1px，以使其与边框和轮廓保持一致。

要为此变更更新您的项目，请将任何 ring 的使用替换为 ring-3：

间距工具类选择器

我们已经更改了space-x-* 和 space-y-* 工具类使用的选择器，以解决大型页面上的严重性能问题：

在渐变中使用变体

在 v3 中，用变体覆盖渐变的一部分会"重置"整个渐变，因此在此示例中，to-* 颜色在深色模式下会是透明的而不是黄色：

容器配置

在 v3 中，container 工具类有几个配置选项，如 center 和 padding，这些在 v4 中不再存在。

要在 v4 中自定义 container 工具类，请使用 @utility 指令扩展它：

默认边框颜色

在 v3 中，border-* 和 divide-* 工具类默认使用您配置的 gray-200 颜色。我们在 v4 中将其更改为 currentColor，以使 Tailwind 更少固执己见并匹配浏览器默认值。

要为此变更更新您的项目，请确保在使用 border-* 或 divide-* 工具类的任何地方指定颜色：

默认环形宽度和颜色

我们已经将 ring 工具类的宽度从 3px 更改为 1px，并将默认颜色从 blue-500 更改为 currentColor，以使事情与 border-*、divide-* 和 outline-* 工具类更加一致。

Preflight 变更

我们在 v4 中对 Preflight 中的基础样式做了一些小的更改：

新的默认占位符颜色

在 v3 中，占位符文本默认使用您配置的 gray-400 颜色。我们在 v4 中简化了这一点，只使用当前文本颜色的 50% 不透明度。

按钮使用默认光标

按钮现在使用 cursor: default 而不是 cursor: pointer 来匹配默认浏览器行为。

移除对话框边距

Preflight 现在重置 <dialog> 元素上的边距，以与其他元素的重置方式保持一致。

使用前缀

前缀现在看起来像变体，并且总是在类名的开头：

添加自定义工具类

在 v3 中，您在 @layer utilities 或 @layer components 中定义的任何自定义类都会被 Tailwind 作为真正的工具类拾取，并且会自动与 hover、focus 或 lg 等变体一起工作，区别在于 @layer components 总是在生成的样式表中排在第一位。

在 v4 中，我们使用原生级联层，不再劫持 @layer at-rule，因此我们引入了 @utility API 作为替代：

变体堆叠顺序

在 v3 中，堆叠的变体从右到左应用，但在 v4 中我们已将它们更新为从左到右应用，以更像 CSS 语法。

任意值中的变量

在 v3 中，您可以在不使用 var() 的情况下将 CSS 变量用作任意值，但最近对 CSS 的更新意味着这通常可能是模糊的，因此我们在 v4 中将此语法更改为使用括号而不是方括号。

移动设备上的悬停样式

在 v4 中，我们已将 hover 变体更新为仅在主要输入设备支持悬停时应用：

过渡轮廓颜色

transition 和 transition-color 工具类现在包含 outline-color 属性。

禁用核心插件

在 v3 中有一个 corePlugins 选项，您可以使用它来完全禁用框架中的某些工具类。这在 v4 中不再受支持。

使用 theme() 函数

由于 v4 为所有主题值包含 CSS 变量，我们建议尽可能使用这些变量而不是 theme() 函数：

使用 JavaScript 配置文件

JavaScript 配置文件仍然支持向后兼容，但在 v4 中不再自动检测。

JavaScript 中的主题值

在 v3 中，我们导出了一个 resolveConfig 函数，您可以使用它将基于 JavaScript 的配置转换为可以在其他 JavaScript 中使用的平面对象。

我们在 v4 中移除了这个功能，希望人们可以直接使用我们生成的 CSS 变量，这更简单，并且会显著减少您的包大小。

与 Vue、Svelte 或 CSS 模块一起使用 @apply

在 v4 中，与您的主要 CSS 文件分开打包的样式表（例如 CSS 模块文件、Vue、Svelte 或 Astro 中的 <style> 块等）无法访问在其他文件中定义的主题变量、自定义工具类和自定义变体。

使用 Sass、Less 和 Stylus

Tailwind CSS v4.0 不是为与 Sass、Less 或 Stylus 等 CSS 预处理器一起使用而设计的。将 Tailwind CSS 本身视为您的预处理器 — 您不应该将 Tailwind 与 Sass 一起使用，原因与您不应该将 Sass 与 Stylus 一起使用相同。因此，无法为您的样式表或 Vue、Svelte、Astro 等中的 <style> 块使用 Sass、Less 或 Stylus。

Learn more in the compatibility documentation.