1. 入门
  2. 升级指南

入门

升级指南

将您的 Tailwind CSS 项目从 v3 升级到 v4。

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

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

使用升级工具

如果您想尝试将项目从 v3 升级到 v4,可以使用我们的升级工具为您完成绝大部分繁重的工作

终端
$ npx @tailwindcss/upgrade@next

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

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

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

最好还浏览一下 v4 中的所有破坏性更改,并很好地了解更改的内容,以防您需要在项目中更新升级工具未捕获的其他内容。

手动升级

使用 PostCSS

在 v3 中,tailwindcss 包是一个 PostCSS 插件,但在 v4 中,PostCSS 插件位于一个专用的 @tailwindcss/postcss 包中。

此外,在 v4 中,导入和供应商前缀现在会自动为您处理,因此如果您的项目中存在 postcss-importautoprefixer,则可以将其删除

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

使用 Vite

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

vite.config.ts
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.cssnpx @tailwindcss/cli -i input.css -o output.css

v3 的更改

以下是 Tailwind CSS v4.0 中所有破坏性更改的完整列表。

我们的 升级工具 将为您自动处理大多数这些更改,因此我们强烈建议您在可以的情况下使用它。

移除了 @tailwind 指令

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

CSS
@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-ellipsistext-ellipsis
decoration-slicebox-decoration-slice
decoration-clonebox-decoration-clone

重命名了实用程序

我们在 v4 中重命名了以下实用程序,以使其更加一致和可预测

v3v4
shadow-smshadow-xs
shadowshadow-sm
drop-shadow-smdrop-shadow-xs
drop-shadowdrop-shadow-sm
blur-smblur-xs
blurblur-sm
rounded-smrounded-xs
roundedrounded-sm
outline-noneoutline-hidden
ringring-3

更新了阴影、半径和模糊刻度

我们重命名了默认的阴影、半径和模糊刻度,以确保每个实用程序都有一个命名值。“裸”版本仍然适用于向后兼容性,但是 <utility>-sm 实用程序的外观会有所不同,除非更新为其各自的 <utility>-xs 版本。

要为这些更改更新您的项目,请将所有 v3 实用程序替换为其 v4 版本

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

重命名了轮廓实用程序

以前的 outline-none 实用程序实际上并未设置 outline-style: none,而是设置了一个不可见的轮廓,出于可访问性原因,它仍然会在强制颜色模式下显示。

为了更清楚地说明这一点,我们将此实用程序重命名为 outline-hidden,并添加了一个新的 outline-none 实用程序,该实用程序实际上设置了 outline-style: none

要为这项更改更新您的项目,请将所有 outline-none 的用法替换为 outline-hidden

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

默认环形宽度更改

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

要更新您的项目以适应此更改,请将所有 ring 的用法替换为 ring-3

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

容器配置

在 v3 中,container 实用程序有几个配置选项,如 centerpadding,这些在 v4 中已不再存在。

要在 v4 中自定义 container 实用程序,请使用 @utility 指令进行扩展

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

预检更改

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

新的默认边框颜色

在 v3 中,边框默认使用您配置的 gray-200 颜色。 我们在 v4 中将其更新为仅使用 currentColor,这与所有浏览器的默认行为一致。

要更新您的项目以适应此更改,请确保您在使用 border 实用程序的任何地方都使用边框颜色实用程序,或者将以下 CSS 行添加到您的项目以保留 v3 的行为

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

新的默认占位符颜色

在 v3 中,占位符文本默认使用您配置的 gray-400 颜色。 我们在 v4 中将其简化为仅使用当前文本颜色,透明度为 50%。

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

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

添加自定义实用程序

在 v3 中,您在 @layer utilities 中定义的任何自定义类都会被 Tailwind 视为真正的实用程序类,并且会自动与 hoverfocuslg 等变体一起使用。

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

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

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

变体堆叠顺序

在 v3 中,堆叠的变体从右向左应用,但在 v4 中,我们已将其更新为从左向右应用,使其看起来更像 CSS 语法。

要更新您的项目以适应此更改,请反转项目中任何对顺序敏感的堆叠变体的顺序

HTML
<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 中更改了此语法以使用括号而不是方括号。

要更新您的项目以适应此更改,请使用新的变量简写语法替换旧的变量简写语法的用法

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

移动设备上的悬停样式

在 v4 中,我们已将 hover 变体更新为仅在主输入设备支持悬停时应用

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

如果您以一种依赖于触摸设备在点击时触发悬停的方式构建了您的网站,这可能会产生问题。 如果这对您来说是一个问题,您可以使用您自己的使用旧实现的变体来覆盖 hover 变体

CSS
@custom-variant hover (&:hover);

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

禁用核心插件

在 v3 中,您可以使用 corePlugins 选项来完全禁用框架中的某些实用程序。 这在 v4 中不再支持。

使用 theme() 函数

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

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

对于您仍然需要使用 theme() 函数的情况(例如,在不支持 CSS 变量的媒体查询中),您应该使用 CSS 变量名称而不是旧的点表示法

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

使用 JavaScript 配置文件

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

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

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

JavaScript 中的主题值

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

我们已经在 v4 中删除了它,希望人们可以直接使用我们生成的 CSS 变量,这样更简单,并且可以显着减小您的包大小。

例如,流行的 React Motion 库允许您在 CSS 变量值之间进行动画处理

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

如果您需要在 JS 中访问已解析的 CSS 变量值,您可以使用 getComputedStyle 获取文档根上主题变量的值

spaghetti.js
let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");
版权所有 © 2025 Tailwind Labs Inc.·商标政策