升级指南

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()），因此该版本无法在旧版浏览器中运行。

如需兼容旧版浏览器，我们建议您暂时继续使用 v3.4 版本。我们正在积极开发兼容模式以帮助用户更快升级，后续将公布更多进展。

移除 @tailwind 指令

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

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

移除已弃用的实用工具

我们移除了 v3 中已弃用且没有文档记录的任何实用工具。以下是已移除的内容及其现代替代品列表：

重命名的实用工具

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

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

我们重命名了默认的阴影、半径和模糊比例，以确保每个实用工具都有一个命名值。虽然 "bare" 版本仍然适用于向后兼容，但 <utility>-sm 实用工具将看起来与各自的 <utility>-xs 版本不同。

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

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

重命名的轮廓实用工具

outline 工具现在默认设置 outline-width: 1px，以便与边框和环形工具更加一致。此外，所有 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" />

默认环宽更改

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

要更新您的项目以适应这一变化，请将任何 ring 的使用替换为 ring-3：

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

空间之间的选择器

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

/* 之前 */
.space-y-4 > :not([hidden]) ~ :not([hidden]) {
  margin-top: 1rem;
}
/* 现在 */
.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">名称</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>

容器配置

在 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 实用工具的宽度从 3px 更改为 1px，并将默认颜色从 blue-500 更改为 currentColor，以使其与 border-*、divide-* 和 outline-* 实用工具保持一致。

要更新您的项目以适应这些更改，请用 ring-3 替换任何 ring 的使用：

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

然后，请确保在依赖默认环颜色的任何地方添加 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);
}

请注意，这些变量仅为兼容性原因而支持，并不被视为 idiomatic 的 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>一个</li>
  <li>两个</li>
  <li>三个</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);

一般来说，我们建议将悬停功能视为增强，而不是依赖于它来使您的网站正常工作，因为触摸设备并不真正具备悬停能力。

过渡轮廓颜色

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

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

在 JavaScript 中的主题值

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

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

例如，流行的 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>你好，世界！</h1>
</template>
<style>
  @reference "../../app.css";
  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

另一个选项是直接使用您的 CSS 主题变量，而不是完全使用 @apply，这也会提高性能，因为 Tailwind 不需要处理这些样式：

<template>
  <h1>你好，世界！</h1>
</template>
<style>
  h1 {
    color: var(--text-red-500);
  }
</style>

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