升级指南

Tailwind CSS v4.0 是该框架的新主要版本，因此尽管我们努力尽量减少破坏性更改，但一些更新还是必要的。本指南概述了将项目从 v3 升级到 v4 所需的所有步骤。

🌐 Tailwind CSS v4.0 is a new major version of the framework, so while we've worked really hard to minimize breaking changes, some updates are necessary. This guide outlines all the steps required to upgrade your projects from v3 to v4.

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

使用升级工具(Using the upgrade tool)

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

🌐 If you'd like to upgrade a project from v3 to v4, you can use our upgrade tool to do the vast majority of the heavy lifting for you:

$ npx @tailwindcss/upgrade

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

🌐 For most projects, the upgrade tool will automate the entire migration process including updating your dependencies, migrating your configuration file to CSS, and handling any changes to your template files.

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

🌐 The upgrade tool requires Node.js 20 or higher, so ensure your environment is updated before running it.

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

同时，最好仔细阅读一下 v4 中的所有重大变更，并充分了解有哪些变化，以防升级工具未捕捉到你项目中其他需要更新的内容。

🌐 It's also a good idea to go over all of the breaking changes in v4 and get a good understanding of what's changed, in case there are other things you need to update in your project that the upgrade tool doesn't catch.

手动升级(Upgrading manually)

使用 PostCSS(Using PostCSS)

在 v3 中，tailwindcss 包是一个 PostCSS 插件，但在 v4 中，PostCSS 插件转移到了一个专门的 @tailwindcss/postcss 包中。

🌐 In v3, the tailwindcss package was a PostCSS plugin, but in v4 the PostCSS plugin lives in a dedicated @tailwindcss/postcss package.

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

🌐 Additionally, in v4 imports and vendor prefixing is now handled for you automatically, so you can remove postcss-import and autoprefixer if they are in your project:

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

使用 Vite(Using Vite)

如果你正在使用 Vite，我们建议从 PostCSS 插件迁移到我们新的专用 Vite 插件，以提高性能并获得最佳的开发者体验：

🌐 If you're using Vite, we recommend migrating from the PostCSS plugin to our new dedicated Vite plugin for improved performance and the best developer experience:

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

使用 Tailwind CLI(Using Tailwind CLI)

在 v4 中，Tailwind CLI 位于一个专用的 @tailwindcss/cli 包中。请将你的任何构建命令更新为使用这个新包：

🌐 In v4, Tailwind CLI lives in a dedicated @tailwindcss/cli package. Update any of your build commands to use the new package instead:

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

与 v3 相比的变化(Changes from v3)

以下是 Tailwind CSS v4.0 中所有重大更改的综合列表。

🌐 Here's a comprehensive list of all the breaking changes in Tailwind CSS v4.0.

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

🌐 Our upgrade tool will handle most of these changes for you automatically, so we highly recommend using it if you can.

浏览器要求(Browser requirements)

Tailwind CSS v4.0 针对现代浏览器设计，支持 Safari 16.4、Chrome 111 和 Firefox 128。我们依赖现代 CSS 功能，如 @property 和 color-mix() 来实现核心框架功能，而 Tailwind CSS v4.0 在旧浏览器中无法使用。

🌐 Tailwind CSS v4.0 is designed for modern browsers and targets Safari 16.4, Chrome 111, and Firefox 128. We depend on modern CSS features like @property and color-mix() for core framework features, and Tailwind CSS v4.0 will not work in older browsers.

如果你需要支持较旧的浏览器，我们建议暂时使用 v3.4。我们正在积极研究一种兼容模式，以帮助用户更快地升级，希望将来能分享更多相关的消息。

🌐 If you need to support older browsers, we recommend sticking with v3.4 for now. We're actively exploring a compatibility mode to help people upgrade sooner that we hope to share more news on in the future.

删除了 @tailwind 指令(Removed @tailwind directives)

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

🌐 In v4 you import Tailwind using a regular CSS @import statement, not using the @tailwind directives you used in v3:

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

删除了弃用的工具(Removed deprecated utilities)

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

🌐 We've removed any utilities that were deprecated in v3 and have been undocumented for several years. Here's a list of what's been removed along with the modern alternative:

重命名工具(Renamed utilities)

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

🌐 We've renamed the following utilities in v4 to make them more consistent and predictable:

更新阴影、半径和模糊比例(Updated shadow, radius, and blur scales)

我们已重命名默认的阴影、半径和模糊比例，以确保每个工具类都有命名值。“裸”版本仍可用于向后兼容，但 <utility>-sm 工具类看起来会有所不同，除非将其更新为相应的 <utility>-xs 版本。

要针对这些更改更新你的项目，请将所有 v3 工具替换为其 v4 版本：

🌐 To update your project for these changes, replace all the v3 utilities with their v4 versions:

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

重命名轮廓工具(Renamed outline utility)

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

🌐 The outline utility now sets outline-width: 1px by default to be more consistent with border and ring utilities. Furthermore all outline-<number> utilities default outline-style to solid, omitting the need to combine them with outline:

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

outline-none 工具以前实际上并没有设置 outline-style: none，而是设置了一个不可见的轮廓，这个轮廓在强制颜色模式下仍然会显示，以满足无障碍需求。

🌐 The outline-none utility previously didn't actually set outline-style: none, and instead set an invisible outline that would still show up in forced colors mode for accessibility reasons.

为了让这一点更加清楚，我们已将此工具重命名为 outline-hidden，并新增了一个真正设置 outline-style: none 的 outline-none 工具。

🌐 To make this more clear we've renamed this utility to outline-hidden and added a new outline-none utility that actually sets outline-style: none.

要将你的项目更新以适应此更改，请将所有 outline-none 的使用替换为 outline-hidden：

🌐 To update your project for this change, replace any usage of outline-none with outline-hidden:

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

默认环宽度更改(Default ring width change)

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

🌐 In v3, the ring utility added a 3px ring. We've changed this in v4 to be 1px to make it consistent with borders and outlines.

要将你的项目更新以适应此更改，请将所有 ring 的使用替换为 ring-3：

🌐 To update your project for this change, replace any usage of ring with ring-3:

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

空格选择器(Space-between selector)

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

🌐 We've changed the selector used by the space-x-* and space-y-* utilities to address serious performance issues on large pages:

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

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

🌐 You might see changes in your project if you were ever using these utilities with inline elements, or if you were adding other margins to child elements to tweak their spacing.

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

🌐 If this change causes any issues in your project, we recommend migrating to a flex or grid layout and using gap instead:

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

分割选择器(Divide selector)

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

🌐 We've changed the selector used by the divide-x-* and divide-y-* utilities to address serious performance issues on large pages:

/* Before */.divide-y-4 > :not([hidden]) ~ :not([hidden]) {  border-top-width: 4px;}/* Now */.divide-y-4 > :not(:last-child) {  border-bottom-width: 4px;}

如果你以前在使用这些实用工具处理内联元素，或者你曾对子元素添加其他边距/填充以调整它们的间距，或者调整特定子元素的边框，你可能会在项目中看到变化。

🌐 You might see changes in your project if you were ever using these utilities with inline elements, if you were adding other margins/padding to child elements to tweak their spacing, or adjusting the borders of specific child elements.

使用带渐变的变体(Using variants with gradients)

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

🌐 In v3, overriding part of a gradient with a variant would "reset" the entire gradient, so in this example the to-* color would be transparent in dark mode instead of yellow:

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

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

🌐 In v4, these values are preserved which is more consistent with how other utilities in Tailwind work.

这意味着如果你想在特定状态下将三段渐变“取消设置”回两段渐变，你可能需要明确使用 via-none：

🌐 This means you may need to explicitly use via-none if you want to "unset" a three-stop gradient back to a two-stop gradient in a specific state:

<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 configuration)

在 v3 中，container 工具有几个配置选项，如 center 和 padding，但在 v4 中已经不存在。

🌐 In v3, the container utility had several configuration options like center and padding that no longer exist in v4.

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

🌐 To customize the container utility in v4, extend it using the @utility directive:

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

默认边框颜色(Default border color)

在 v3 中，border-* 和 divide-* 工具默认使用你配置的 gray-200 颜色。我们在 v4 中将其更改为 currentColor，以使 Tailwind 不那么具有主观性，并与浏览器默认值一致。

🌐 In v3, the border-* and divide-* utilities used your configured gray-200 color by default. We've changed this to currentColor in v4 to make Tailwind less opinionated and match browser defaults.

要更新你的项目以适应此更改，请确保在使用 border-* 或 divide-* 工具类的任何地方指定颜色：

🌐 To update your project for this change, make sure you specify a color anywhere you're using a border-* or divide-* utility:

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

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

🌐 Alternatively, add these base styles to your project to preserve the v3 behavior:

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

默认环宽度和颜色(Default ring width and color)

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

🌐 We've changed the width of the ring utility from 3px to 1px and changed the default color from blue-500 to currentColor to make things more consistent the border-*, divide-*, and outline-* utilities.

要将你的项目更新以适应这些更改，请将所有使用 ring 的地方替换为 ring-3：

🌐 To update your project for these changes, replace any use of ring with ring-3:

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

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

🌐 Then make sure to add ring-blue-500 anywhere you were depending on the default ring color:

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

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

🌐 Alternatively, add these theme variables to your CSS to preserve the v3 behavior:

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

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

🌐 Note though that these variables are only supported for compatibility reasons, and are not considered idiomatic usage of Tailwind CSS v4.0.

预检更改(Preflight changes)

我们对 v4 中 Preflight 的基本样式做了一些小改动：

🌐 We've made a couple small changes to the base styles in Preflight in v4:

新的默认占位符颜色(New default placeholder color)

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

🌐 In v3, placeholder text used your configured gray-400 color by default. We've simplified this in v4 to just use the current text color at 50% opacity.

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

🌐 You probably won't even notice this change (it might even make your project look better), but if you want to preserve the v3 behavior, add this CSS to your project:

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

按钮使用默认光标(Buttons use the default cursor)

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

🌐 Buttons now use cursor: default instead of cursor: pointer to match the default browser behavior.

如果你想继续默认使用 cursor: pointer，请将以下基础样式添加到你的 CSS 中：

🌐 If you'd like to continue using cursor: pointer by default, add these base styles to your CSS:

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

对话框边距已删除(Dialog margins removed)

预检现在将 <dialog> 元素的边距重置为与其他元素重置时一致。

🌐 Preflight now resets margins on <dialog> elements to be consistent with how other elements are reset.

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

🌐 If you still want dialogs to be centered by default, add this CSS to your project:

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

隐藏属性优先(Hidden attribute takes priority)

像 block 或 flex 这样的显示类不再优先于元素上的 hidden 属性。如果你希望元素对用户可见，请移除 hidden 属性。请注意，这不适用于 hidden="until-found"。

🌐 Display classes like block or flex no longer take priority over the hidden attribute on an element. Remove the hidden attribute if you want an element to be visible to the user. Note that this does not apply to hidden="until-found".

使用前缀(Using a prefix)

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

🌐 Prefixes now look like variants and are always at the beginning of the class name:

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

使用前缀时，你仍应像不使用前缀一样配置主题变量：

🌐 When using a prefix, you should still configure your theme variables as if you aren't using a prefix:

@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 变量将包括一个前缀，以避免与项目中已有的变量冲突：

🌐 The generated CSS variables will include a prefix to avoid conflicts with any existing variables in your project:

: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);  /* ... */}

重要的修饰语(The important modifier)

在 v3 中，你可以通过在工具名称的开头（但在任何变体之后）放置 ! 来将工具标记为重要。在 v4 中，你应该将 ! 放在类名的最末尾：

🌐 In v3 you could mark a utility as important by placing an ! at the beginning of the utility name (but after any variants). In v4 you should place the ! at the very end of the class name instead:

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

旧方法仍然支持以保持兼容性，但已被弃用。

🌐 The old way is still supported for compatibility but is deprecated.

添加自定义工具(Adding custom utilities)

在 v3 中，你在 @layer utilities 或 @layer components 内定义的任何自定义类都会被 Tailwind 识别为真正的工具类，并会自动兼容像 hover、focus 或 lg 这样的变体，不同之处在于 @layer components 总是会在生成的样式表中排在最前面。

🌐 In v3, any custom classes you defined within @layer utilities or @layer components would get picked up by Tailwind as a true utility class and would automatically work with variants like hover, focus, or lg with the difference being that @layer components would always come first in the generated stylesheet.

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

🌐 In v4 we are using native cascade layers and no longer hijacking the @layer at-rule, so we've introduced the @utility API as a replacement:

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

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

🌐 Custom utilities are now also sorted based on the amount of properties they define. This means that component utilities like this .btn can be overwritten by other Tailwind utilities without additional configuration:

@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;}

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

🌐 Learn more about registering custom utilities in the adding custom utilities documentation.

变体堆叠顺序(Variant stacking order)

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

🌐 In v3, stacked variants were applied from right to left, but in v4 we've updated them to apply left to right to look more like CSS syntax.

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

🌐 To update your project for this change, reverse the order of any order-sensitive stacked variants in your project:

<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）是你最有可能使用的，即便如此，也只有在你将它们与其他变体叠加使用时才会用到。

🌐 You likely have very few of these if any—the direct child variant (*) and any typography plugin variants (prose-headings) are the most likely ones you might be using, and even then it's only if you've stacked them with other variants.

任意值的变量(Variables in arbitrary values)

在 v3 中，你可以将 CSS 变量作为任意值使用，而无需 var()，但最近 CSS 的更新意味着这通常可能会产生歧义，所以我们在 v4 中将此语法改为使用圆括号而不是方括号。

🌐 In v3 you were able to use CSS variables as arbitrary values without var(), but recent updates to CSS mean that this can often be ambiguous, so we've changed the syntax for this in v4 to use parentheses instead of square brackets.

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

🌐 To update your project for this change, replace usage of the old variable shorthand syntax with the new variable shorthand syntax:

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

网格和对象定位工具中的任意值(Arbitrary values in grid and object-position utilities)

在 grid-cols-*、grid-rows-* 和 object-* 工具中的任意值内，逗号之前被替换为空格。这种特殊行为在 Tailwind CSS v3 中存在，以兼容 v2。但在 v4.0 中这种兼容性已不存在，必须使用下划线来表示空格。

🌐 Commas were previously replaced with spaces in the grid-cols-*, grid-rows-*, and object-* utilities inside arbitrary values. This special behavior existed in Tailwind CSS v3 for compatibility with v2. This compatibility no longer exists in v4.0 and underscores must be used to represent spaces.

要为此更改更新你的项目，请将原本用作空格的逗号替换为下划线：

🌐 To update your project for this change, replace usage of commas that were intended to be spaces with underscores:

<div class="grid-cols-[max-content,auto]"></div><div class="grid-cols-[max-content_auto]"></div>

移动设备上的悬停样式(Hover styles on mobile)

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

🌐 In v4 we've updated the hover variant to only apply when the primary input device supports hover:

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

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

🌐 This can create problems if you've built your site in a way that depends on touch devices triggering hover on tap. If this is an issue for you, you can override the hover variant with your own variant that uses the old implementation:

@custom-variant hover (&:hover);

一般来说，我们建议将悬停功能视为一种增强功能，而不是依赖它来让你的网站正常工作，因为触摸设备实际上没有悬停功能。

🌐 Generally though we recommend treating hover functionality as an enhancement, and not depending on it for your site to work since touch devices don't truly have the ability to hover.

过渡轮廓颜色(Transitioning outline-color)

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

🌐 The transition and transition-colors utilities now include the outline-color property.

这意味着，如果你在获得焦点时添加了带有自定义颜色的轮廓，你将会看到颜色从默认颜色过渡。为了避免这种情况，请确保无条件设置轮廓颜色，或者明确为两种状态都设置颜色：

🌐 This means if you were adding an outline with a custom color on focus, you will see the color transition from the default color. To avoid this, make sure you set the outline color unconditionally, or explicitly set it for both states:

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

单独的变换属性(Individual transform properties)

rotate-*、scale-* 和 translate-* 工具现在基于 CSS 中的各自 rotate、scale 和 translate 属性。通常这不应该影响行为，但有几个情况需要注意：

🌐 The rotate-*, scale-*, and translate-* utilities are now based on the individual rotate, scale, and translate properties in CSS. Normally this shouldn't affect the behavior but there's a couple of cases to look out for:

重置变换(Resetting Transforms)

你以前可以通过 transform-none 来“重置”你的旋转、缩放和移动工具。现在这种方法不再有效，你需要分别重置各个属性：

🌐 You previously would've been able to "reset" your rotate, scale, and translate utilities via transform-none. This no longer works and you will need to reset the individual properties instead:

<button class="scale-150 focus:transform-none"></button><button class="scale-150 focus:scale-none"></button>

过渡(Transitions)

如果你自定义了要过渡的属性列表并包含 transform（例如通过写 transition-[opacity,transform]），那么这些工具将不再进行过渡。要解决此问题，请在列表中包含单独的属性。例如，如果你希望在使用 opacity-* 和 scale-* 工具时进行过渡，应使用 transition-[opacity,scale] 代替。

🌐 If you customize the list of transitioned properties and include transform (e.g. by writing transition-[opacity,transform]) then these utilities will no longer transition. To fix this, include the individual properties in the list. For example, if you want to transition changes when using opacity-* and scale-* utilities you should use transition-[opacity,scale] instead.

<button class="transition-[opacity,transform] hover:scale-150"></button><button class="transition-[opacity,scale] hover:scale-150"></button>

禁用核心插件(Disabling core plugins)

在 v3 中，有一个 corePlugins 选项可以用来完全禁用框架中的某些工具。但在 v4 中已不再支持此功能。

🌐 In v3 there was a corePlugins option you could use to completely disable certain utilities in the framework. This is no longer supported in v4.

使用 theme() 函数(Using the theme() function)

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

🌐 Since v4 includes CSS variables for all of your theme values, we recommend using those variables instead of the theme() function whenever possible:

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

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

🌐 For cases where you still need to use the theme() function (like in media queries where CSS variables aren't supported), you should use the CSS variable name instead of the old dot notation:

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

使用 JavaScript 配置文件(Using a JavaScript config file)

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

🌐 JavaScript config files are still supported for backward compatibility, but they are no longer detected automatically in v4.

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

🌐 If you still need to use a JavaScript config file, you can load it explicitly using the @config directive:

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

基于 JavaScript 的配置中的 corePlugins、safelist 和 separator 选项在 v4.0 中不受支持。要在 v4 中将工具列入安全列表，请使用 @source inline()。

🌐 The corePlugins, safelist, and separator options from the JavaScript-based config are not supported in v4.0. To safelist utilities in v4 use @source inline().

JavaScript 中的主题值(Theme values in JavaScript)

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

🌐 In v3 we exported a resolveConfig function that you could use to turn your JavaScript-based config into a flat object that you could use in your other JavaScript.

我们在 v4 中删除了它，希望人们可以直接使用我们生成的 CSS 变量，这要简单得多，并且可以显著减少你的包大小。

🌐 We've removed this in v4 in hopes that people can use the CSS variables we generate directly instead, which is much simpler and will significantly reduce your bundle size.

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

🌐 For example, the popular Motion library for React lets you animate to and from CSS variable values:

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

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

🌐 If you need access to a resolved CSS variable value in JS, you can use getComputedStyle to get the value of a theme variable on the document root:

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

将 @apply 与 Vue、Svelte 或 CSS 模块一起使用(Using @apply with Vue, Svelte, or CSS modules)

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

🌐 In v4, stylesheets that are bundled separately from your main CSS file (e.g. CSS modules files, <style> blocks in Vue, Svelte, or Astro, etc.) do not have access to theme variables, custom utilities, and custom variants defined in other files.

要在这些上下文中使用这些定义，请使用 @reference 导入它们，而无需在你的包中重复任何 CSS：

🌐 To make these definitions available in these contexts, use @reference to import them without duplicating any CSS in your bundle:

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

或者，你可以直接使用你的 CSS 主题变量，而不使用 @apply，这也会提高性能，因为 Tailwind 不需要处理这些样式：

🌐 Alternatively, you can use your CSS theme variables directly instead of using @apply at all, which will also improve performance since Tailwind won't need to process these styles:

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

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

🌐 You can find more documentation on using Tailwind with CSS modules.

使用 Sass、Less 和 Stylus(Using Sass, Less, and Stylus)

Tailwind CSS v4.0 并不设计用于与 Sass、Less 或 Stylus 等 CSS 预处理器一起使用。可以把 Tailwind CSS 本身看作是你的预处理器——你不应该将 Tailwind 与 Sass 一起使用，就像你不会将 Sass 与 Stylus 一起使用一样。因此，在 Vue、Svelte、Astro 等中，你的样式表或 <style> 块无法使用 Sass、Less 或 Stylus。

🌐 Tailwind CSS v4.0 is not designed to be used with CSS preprocessors like Sass, Less, or Stylus. Think of Tailwind CSS itself as your preprocessor — you shouldn't use Tailwind with Sass for the same reason you wouldn't use Sass with Stylus. Because of this it is not possible to use Sass, Less, or Stylus for your stylesheets or <style> blocks in Vue, Svelte, Astro, etc.

在兼容性文档中了解更多信息。

🌐 Learn more in the compatibility documentation.