入门
将您的 Tailwind CSS 项目从 v3 升级到 v4。
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 中的所有 破坏性变更 也是一个好主意，以了解变更的具体情况，以防您需要在升级工具未捕获的情况下更新项目中的其他内容。
在 v3 中，tailwindcss 包是一个 PostCSS 插件，但在 v4 中，PostCSS 插件位于专用的 @tailwindcss/postcss 包中。
此外，在 v4 中，导入和供应商前缀现在会自动处理，因此如果您的项目中有 postcss-import 和 autoprefixer，可以将其移除：
export default { plugins: { "postcss-import": {}, tailwindcss: {}, autoprefixer: {}, "@tailwindcss/postcss": {}, },};如果您在使用 Vite，我们建议从 PostCSS 插件迁移到我们新的专用 Vite 插件，以提高性能和开发体验：
import { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({ plugins: [ tailwindcss(), ],});在 v4 中，Tailwind CLI 位于专用的 @tailwindcss/cli 包中。更新您的构建命令以改用新包：
npx tailwindcss -i input.css -o output.cssnpx @tailwindcss/cli -i input.css -o output.css下面是 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。我们正在积极探索兼容模式，以帮助人们更早地升级，我们希望在未来分享更多消息。
在 v4 中，您通过常规 CSS @import 语句导入 Tailwind，而不是使用您在 v3 中使用的 @tailwind 指令：
@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";我们已删除在 v3 中被弃用并且多年未记录的任何工具。以下是移除的内容及其现代替代方案的列表：
| 弃用 | 替代 |
|---|---|
bg-opacity-* | 使用透明度修饰符，如 bg-black/50 |
text-opacity-* | 使用透明度修饰符，如 text-black/50 |
border-opacity-* | 使用透明度修饰符，如 border-black/50 |
divide-opacity-* | 使用透明度修饰符，如 divide-black/50 |
ring-opacity-* | 使用透明度修饰符，如 ring-black/50 |
placeholder-opacity-* | 使用透明度修饰符，如 placeholder-black/50 |
flex-shrink-* | shrink-* |
flex-grow-* | grow-* |
overflow-ellipsis | text-ellipsis |
decoration-slice | box-decoration-slice |
decoration-clone | box-decoration-clone |
我们在 v4 中对以下工具进行了改名，以使其更加一致和可预测：
| v3 | v4 |
|---|---|
shadow-sm | shadow-xs |
shadow | shadow-sm |
drop-shadow-sm | drop-shadow-xs |
drop-shadow | drop-shadow-sm |
blur-sm | blur-xs |
blur | blur-sm |
backdrop-blur-sm | backdrop-blur-xs |
backdrop-blur | backdrop-blur-sm |
rounded-sm | rounded-xs |
rounded | rounded-sm |
outline-none | outline-hidden |
ring | ring-3 |
我们已更改默认影子、半径和模糊规模的名称，以确保每个工具都有命名值。“裸”版本仍然可以为了向后兼容，但 <utility>-sm 工具的外观将不同，除非更新为各自的 <utility>-xs 版本。
要使您的项目更新这些变更，请将所有 v3 工具替换为其 v4 版本：
<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 的使用替换为 ring-3：
<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);}请注意，这些变量仅在兼容性方面得到支持，并且不被视为 Tailwind CSS v4.0 的规范用法。
我们在 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 中不再支持此功能。
由于 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 配置文件在 v4 中仍受支持，但不再自动检测。
如果您仍需要使用 JavaScript 配置文件，您可以通过 @config 指令显式加载它：
@config "../../tailwind.config.js";JavaScript 配置中的 corePlugins、safelist 和 separator 选项在 v4.0 中不受支持。
在 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");在 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 模块中找到更多文档。
Tailwind CSS v4.0 并不设计为与 CSS 预处理器如 Sass、Less 或 Stylus 一起使用。可以将 Tailwind CSS 本身视为您的预处理器——您不应该将 Tailwind 与 Sass 一起使用，原因与您不应该将 Sass 与 Stylus 一起使用相同。因此，您无法在 Vue、Svelte、Astro 等中的样式表或 <style> 块中使用 Sass、Less 或 Stylus。
在兼容性文档中了解更多信息。