升级指南

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.

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

¥To simplify the process, we’ve developed a migration tool that can automatically handle the bulk of these changes for you in typical projects.

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

¥Using the upgrade tool

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

¥If you'd like to try upgrading 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.

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

¥We recommend running the upgrade tool in a new branch, then carefully reviewing the diff and testing your project in the browser to make sure all of the changes look correct. You may need to tweak a few things by hand in complex projects, but the tool will save you a ton of time either way.

仔细检查 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)

¥Upgrading manually

使用 PostCSS(Using 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)

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

¥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.css
npx @tailwindcss/cli -i input.css -o output.css

与 v3 相比的变化(Changes from 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.

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

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

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

¥Renamed utilities

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

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

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

¥Updated shadow, radius, and blur scales

我们已重命名默认阴影、半径和模糊比例，以确保每个工具都有一个命名值。"bare" 版本仍可用于向后兼容，但 <utility>-sm 工具看起来会有所不同，除非更新到各自的 <utility>-xs 版本。

¥We've renamed the default shadow, radius and blur scales to make sure every utility has a named value. The "bare" versions still work for backward compatibility, but the <utility>-sm utilities will look different unless updated to their respective <utility>-xs versions.

要针对这些更改更新你的项目，请将所有 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)

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

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

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

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

这意味着，如果你想将三级梯度 "unset" 恢复为特定状态下的两级梯度，则可能需要明确使用 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)

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

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

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

¥Preflight changes

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

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

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

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

¥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 margins removed

Preflight 现在重置 <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;
  }
}

使用前缀(Using a prefix)

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

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

¥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 规则，因此我们引入了 @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)

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

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

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

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

¥Transitioning outline-color

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

¥The transition and transition-color 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>

禁用核心插件(Disabling core plugins)

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

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

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

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

¥The corePlugins, safelist, and separator options from the JavaScript-based config are not supported in v4.0.

JavaScript 中的主题值(Theme values in 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 运动 库允许你为 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)

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