升级指南

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.css
npx @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 中重命名了以下实用工具，使其更加一致和可预测

更新了阴影、半径和模糊比例

我们重命名了默认的阴影、半径和模糊比例，以确保每个实用工具都有一个命名值。“裸”版本仍然可以向后兼容，但 <utility>-sm 实用工具的外观将有所不同，除非更新为各自的 <utility>-xs 版本。

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

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

重命名了 outline 实用工具

outline 实用工具现在默认设置 outline-width: 1px，以便与边框和 ring 实用工具更加一致。此外，所有 outline-<number> 实用工具默认将 outline-style 设置为 solid，从而无需将其与 outline 结合使用

<input class="outline outline-2" />
<input class="outline-2" />

之前的 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" />

默认 ring 宽度更改

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

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

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

Space-between 选择器

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

/* Before */
.space-y-4 > :not([hidden]) ~ :not([hidden]) {
  margin-top: 1rem;
}
/* Now */
.space-y-4 > :not(:last-child) {
  margin-bottom: 1rem;
}

如果您曾经将这些实用工具与内联元素一起使用，或者如果您向子元素添加了其他边距以调整其间距，则可能会在您的项目中看到更改。

如果此更改在您的项目中引起任何问题，我们建议迁移到 flex 或 grid 布局并使用 gap 代替

<div class="space-y-4 p-4">
<div class="flex flex-col gap-4 p-4">
  <label for="name">Name</label>
  <input type="text" name="name" />
</div>

将变体与渐变一起使用

在 v3 中，使用变体覆盖渐变的一部分会“重置”整个渐变，因此在此示例中，to-* 颜色在暗黑模式下将变为透明而不是黄色

<div class="bg-gradient-to-r from-red-500 to-yellow-400 dark:from-blue-500">
  <!-- ... -->
</div>

在 v4 中，这些值被保留，这与 Tailwind 中其他实用工具的工作方式更加一致。

这意味着如果您想将三步渐变“取消设置”回特定状态下的两步渐变，则可能需要显式使用 via-none

<div class="bg-linear-to-r from-red-500 via-orange-400 to-yellow-400 dark:via-none dark:from-blue-500 dark:to-teal-400">
  <!-- ... -->
</div>

Container 配置

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

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

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

默认边框颜色

在 v3 中，border-* 和 divide-* 实用工具默认使用您配置的 gray-200 颜色。我们在 v4 中将其更改为 currentColor，以使 Tailwind 不那么武断并匹配浏览器默认值。

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

<div class="border border-gray-200 px-2 py-3 ...">
  <!-- ... -->
</div>

或者，将这些基础样式添加到您的项目中以保留 v3 行为

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

默认 ring 宽度和颜色

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

要为这些更改更新您的项目，请将任何 ring 的用法替换为 ring-3

<button class="focus:ring ...">
<button class="focus:ring-3 ...">
  <!-- ... -->
</button>

然后确保在您依赖默认 ring 颜色的任何地方添加 ring-blue-500

<button class="focus:ring-3 focus:ring-blue-500 ...">
  <!-- ... -->
</button>

或者，将这些主题变量添加到您的 CSS 中以保留 v3 行为

@theme {
  --default-ring-width: 3px;
  --default-ring-color: var(--color-blue-500);
}

但请注意，这些变量仅出于兼容性原因而受支持，并且不被认为是 Tailwind CSS v4.0 的惯用用法。

Preflight 更改

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

新的默认占位符颜色

在 v3 中，占位符文本默认使用您配置的 gray-400 颜色。我们在 v4 中对此进行了简化，仅使用当前文本颜色（不透明度为 50%）。

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

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

按钮使用默认光标

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

如果您想继续默认使用 cursor: pointer，请将这些基础样式添加到您的 CSS 中

@layer base {
  button:not(:disabled),
  [role="button"]:not(:disabled) {
    cursor: pointer;
  }
}

已移除对话框边距

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

如果您仍然希望对话框默认居中，请将此 CSS 添加到您的项目中

@layer base {
  dialog {
    margin: auto;
  }
}

使用前缀

前缀现在看起来像变体，并且始终位于类名的开头

<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600">
  <!-- ... -->
</div>

使用前缀时，您仍然应该配置您的主题变量，就像您未使用前缀一样

@import "tailwindcss" prefix(tw);
@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-200: oklch(0.98 0.04 113.22);
  --color-avocado-300: oklch(0.94 0.11 115.03);
  /* ... */
}

生成的 CSS 变量将包含前缀，以避免与项目中的任何现有变量冲突

:root {
  --tw-font-display: "Satoshi", "sans-serif";
  --tw-breakpoint-3xl: 120rem;
  --tw-color-avocado-100: oklch(0.99 0 0);
  --tw-color-avocado-200: oklch(0.98 0.04 113.22);
  --tw-color-avocado-300: oklch(0.94 0.11 115.03);
  /* ... */
}

添加自定义实用工具

在 v3 中，您在 @layer utilities 或 @layer components 中定义的任何自定义类都将被 Tailwind 视为真正的实用工具类，并将自动与 hover、focus 或 lg 等变体一起使用，不同之处在于 @layer components 将始终在生成的样式表中排在第一位。

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

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

自定义实用工具现在也根据它们定义的属性数量进行排序。这意味着像 .btn 这样的组件实用工具可以被其他 Tailwind 实用工具覆盖，而无需额外的配置

@layer components {
  .btn {
    border-radius: 0.5rem;
    padding: 0.5rem 1rem;
    background-color: ButtonFace;
  }
}
@utility btn {
  border-radius: 0.5rem;
  padding: 0.5rem 1rem;
  background-color: ButtonFace;
}

了解有关注册自定义实用工具的更多信息，请参阅添加自定义实用工具文档。

变体堆叠顺序

在 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 中，您可以将 CSS 变量用作任意值，而无需 var()，但最近 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);

但总的来说，我们建议将悬停功能视为一种增强功能，而不是依赖它来使您的站点正常工作，因为触摸设备实际上不具备悬停能力。

过渡 outline-color

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

这意味着如果您在焦点上添加了具有自定义颜色的轮廓，您将看到颜色从默认颜色过渡。为避免这种情况，请确保您无条件地设置轮廓颜色，或为两种状态显式设置轮廓颜色

<button class="transition hover:outline-2 hover:outline-cyan-500"></button>
<button class="outline-cyan-500 transition hover:outline-2"></button>

禁用核心插件

在 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";

v4.0 中不支持基于 JavaScript 的配置中的 corePlugins、safelist 和 separator 选项。

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");

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

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

为了使这些定义在这些上下文中可用，请使用 @reference 导入它们，而无需在您的捆绑包中复制任何 CSS

<template>
  <h1>Hello world!</h1>
</template>
<style>
  @reference "../../app.css";
  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

或者，您可以直接使用您的 CSS 主题变量，而不是完全使用 @apply，这也将提高性能，因为 Tailwind 无需处理这些样式

<template>
  <h1>Hello world!</h1>
</template>
<style>
  h1 {
    color: var(--text-red-500);
  }
</style>

您可以在将 Tailwind 与 CSS 模块一起使用中找到更多文档。