Upgrade guide

Tailwind CSS v4.0 是框架的一个新的主要版本，虽然我们已经尽力减少破坏性更改，但某些更新仍然是必要的。本指南概述了将项目从 v3 升级到 v4 所需的所有步骤。

为了简化这个过程，我们开发了一个迁移工具，可以在典型项目中自动处理大部分这些更改。

使用升级工具

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

$ npx @tailwindcss/upgrade@next

对于大多数项目，升级工具会自动完成整个迁移过程，包括更新依赖项、将配置文件迁移到 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 指令

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

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

移除已弃用的工具类

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

重命名的工具类

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

更新的阴影、圆角和模糊比例

我们已重命名默认的阴影、圆角和模糊比例，以确保每个工具类都有一个命名值。"裸"版本仍然可以向后兼容工作，但除非更新为相应的 <utility>-xs 版本，否则 <utility>-sm 工具类的外观会有所不同。

要为这些更改更新您的项目，请将所有 v3 工具类替换为它们的 v4 版本：

<input class="shadow-sm" /><input class="shadow-xs" /><input class="shadow" /><input class="shadow-sm" />

重命名的轮廓工具类

outline-none 工具类以前实际上并没有设置 outline-style: none，而是设置了一个在强制颜色模式下仍然可见的不可见轮廓，以实现可访问性。

为了使这一点更清晰，我们已将此工具类重命名为 outline-hidden，并添加了一个新的 outline-none 工具类，它实际上设置了 outline-style: none。

要为此更改更新您的项目，请将任何 outline-none 的使用替换为 outline-hidden：

<input class="focus:outline-none" /><input class="focus:outline-hidden" />

默认环宽度更改

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

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

<input class="ring ring-blue-500" /><input class="ring-3 ring-blue-500" />

容器配置

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

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

@utility container {  margin-inline: auto;  padding-inline: 2rem;}

Preflight 更改

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

新的默认边框颜色

在 v3 中，边框默认使用您配置的 gray-200 颜色。在 v4 中，我们将其更新为仅使用 currentColor，这与所有浏览器的默认行为相匹配。

要为此更改更新您的项目，请确保在使用 border 工具类的任何地方使用边框颜色工具类，或者添加这些 CSS 行以保留 v3 行为：

@layer base {  *,  ::after,  ::before,  ::backdrop,  ::file-selector-button {    border-color: var(--color-gray-200, currentColor);  }}

新的默认占位符颜色

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

您可能甚至不会注意到这一变化（它甚至可能使您的项目看起来更好），但如果您想保留 v3 行为，请将此 CSS 添加到您的项目中：

@layer base {  input::placeholder,  textarea::placeholder {    color: theme(--color-gray-400);  }}

添加自定义工具类

在 v3 中，您在 @layer utilities 中定义的任何自定义类都会被 Tailwind 视为真正的工具类，并会自动与 hover、focus 或 lg 等变体一起工作。

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

@layer utilities {  .tab-4 {    tab-size: 4;  }}@utility tab-4 {  tab-size: 4;}

了解有关在添加自定义工具类文档中注册自定义工具类的更多信息。

变体堆叠顺序

在 v3 中，堆叠变体从右到左应用，但在 v4 中，我们将其更新为从左到右应用，以使其看起来更像 CSS 语法。

要为此更改更新您的项目，请反转项目中任何对顺序敏感的堆叠变体的顺序：

<ul class="py-4 first:*:pt-0 last:*:pb-0"><ul class="py-4 *:first:pt-0 *:last:pb-0">  <li>One</li>  <li>Two</li>  <li>Three</li></ul>

您可能几乎没有这些变体——直接子变体（*）和任何排版插件变体（prose-headings）是您可能使用的最可能的变体，即使这样，也只有在您将它们与其他变体堆叠时才会使用。

任意值中的变量

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

要为此更改更新您的项目，请将旧的变量简写语法替换为新的变量简写语法：

<div class="bg-[--brand-color]"></div><div class="bg-(--brand-color)"></div>

移动设备上的悬停样式

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

@media (hover: hover) {  .hover\:underline:hover {    text-decoration: underline;  }}

如果您构建网站的方式依赖于触摸设备在点击时触发悬停，这可能会导致问题。如果这是您的问题，您可以使用旧的实现覆盖 hover 变体：

@custom-variant hover (&:hover);

通常，我们建议将悬停功能视为一种增强功能，并且不依赖于它来使您的网站正常工作，因为触摸设备实际上没有悬停的能力。

禁用核心插件

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

使用 theme() 函数

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

.my-class {  background-color: theme(colors.red.500);  background-color: var(--color-red-500);}

对于仍然需要使用 theme() 函数的情况（例如在不支持 CSS 变量的媒体查询中），您应该使用 CSS 变量名称而不是旧的点表示法：

@media (width >= theme(screens.xl)) {@media (width >= theme(--breakpoint-xl)) {  /* ... */}

使用 JavaScript 配置文件

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

如果您仍然需要使用 JavaScript 配置文件，可以使用 @config 指令显式加载它：

@config "../../tailwind.config.js";

JavaScript 中的主题值

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

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

例如，流行的 React 库 Motion 允许您在 CSS 变量值之间进行动画：

<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />

如果您需要在 JS 中访问已解析的 CSS 变量值，可以使用 getComputedStyle 获取文档根上的主题变量值：

let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");