首页 / Tailwind CSS 入门教程 / v3到v4迁移指南（一）：核心差异

← 上一篇 下一篇 →
Tailwind CSS 入门教程

v3到v4迁移指南（一）：核心差异

本教程共 50 篇 · 第 46 篇 · 更新于 2026-07-29 · 约 8 分钟阅读

Tailwind CSSTailwind CSS 入门教程迁移v3到v4upgradebreaking changes

46. v3 到 v4 迁移指南（一）：核心差异

本节目标：全面了解 v3 到 v4 的核心差异，包括配置方式变化、废弃工具类、重命名工具类，为项目迁移做好准备。

v4 是个大版本升级，虽然官方尽力减少了破坏性变更，但核心机制的变化还是逃不掉。搞清楚这些差异，迁移才能少踩坑。

配置方式变化

v3：JavaScript 配置

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,jsx}'],
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
  plugins: [],
}

v4：CSS-first 配置

/* app.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.65 0.21 259.815);
}

v4 默认不需要 tailwind.config.js，所有配置都在 CSS 里完成。如果需要兼容旧配置，可以用 @config 指令：

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

入口导入变化

v3

@tailwind base;
@tailwind components;
@tailwind utilities;

v4

@import "tailwindcss";

一行搞定。@tailwind 指令在 v4 中已废弃。

废弃的工具类

以下工具类在 v4 中被移除，需要使用新的替代方案：

废弃写法v4 替代方案
bg-opacity-50bg-black/50
text-opacity-50text-black/50
border-opacity-50border-black/50
divide-opacity-50divide-black/50
ring-opacity-50ring-black/50
placeholder-opacity-50placeholder-black/50
flex-shrink-*shrink-*
flex-grow-*grow-*
overflow-ellipsistext-ellipsis
decoration-slicebox-decoration-slice
decoration-clonebox-decoration-clone
<!-- v3 写法 -->
<div class="bg-blue-500 bg-opacity-50">半透明背景</div>

<!-- v4 写法 -->
<div class="bg-blue-500/50">半透明背景</div>

重命名工具类

为了保持一致性，一些工具类在 v4 中被重命名：

阴影、模糊、圆角

v3v4
shadow-smshadow-xs
shadowshadow-sm
drop-shadow-smdrop-shadow-xs
drop-shadowdrop-shadow-sm
blur-smblur-xs
blurblur-sm
backdrop-blur-smbackdrop-blur-xs
backdrop-blurbackdrop-blur-sm
rounded-smrounded-xs
roundedrounded-sm
<!-- v3 -->
<input class="shadow-sm rounded-sm blur-sm">

<!-- v4 -->
<input class="shadow-xs rounded-xs blur-xs">

outline 工具类

v3v4
outline-noneoutline-hidden
outlineoutline-1（默认宽度变为 1px）
<!-- v3 -->
<input class="focus:outline-none">

<!-- v4 -->
<input class="focus:outline-hidden">

v4 中新增了一个真正的 outline-none，它设置 outline-style: none，与 v3 的 outline-none 行为不同。

ring 默认宽度

<!-- v3：ring 默认 3px -->
<input class="ring ring-blue-500">

<!-- v4：ring 默认 1px，需要 ring-3 达到原来效果 -->
<input class="ring-3 ring-blue-500">

浏览器要求

v4 依赖现代 CSS 特性，浏览器要求更高：

  • Chrome 111+（2023 年 3 月）
  • Safari 16.4+（2023 年 3 月）
  • Firefox 128+（2024 年 7 月）

如果需要支持旧浏览器，建议继续使用 v3.4（支持到 2027 年 2 月）。

安装方式变化

v3 安装

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init
// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

v4 安装

# 推荐：Vite 插件
npm install tailwindcss @tailwindcss/vite

# 或 PostCSS 插件
npm install tailwindcss @tailwindcss/postcss

# 或 CLI
npm install tailwindcss @tailwindcss/cli
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

v4 自动处理导入和前缀，不再需要 postcss-import 和 autoprefixer。

暗黑模式变化

v3

// tailwind.config.js
module.exports = {
  darkMode: 'class',  // 或 'media'
}
<html class="dark">
  <div class="bg-white dark:bg-gray-900">
</html>

v4

/* 默认使用 prefers-color-scheme */
/* 或手动定义 */
@custom-variant dark (&:where(.dark, .dark *));
<html class="dark">
  <div class="bg-white dark:bg-gray-900">
</html>

自定义工具类变化

v3

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

v4

@utility tab-4 {
  tab-size: 4;
}

v4 的 @utility 注册的类自动支持变体（hover、focus 等）。

变体堆叠顺序

v3 中变体从右到左应用，v4 改为从左到右：

<!-- v3 -->
<ul class="py-4 first:*:pt-0 last:*:pb-0">

<!-- v4 -->
<ul class="py-4 *:first:pt-0 *:last:pb-0">

任意值中的变量

v3

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

v4

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

括号语法避免了歧义。

重要修饰符位置

v3

<div class="!flex !bg-red-500">

v4

<div class="flex! bg-red-500!">

! 从类首移到类尾。v3 写法仍支持但已废弃。

Tip

这些差异看起来多，但迁移工具（npx @tailwindcss/upgrade）可以自动处理大部分。建议先在分支上运行迁移工具，然后人工检查关键部分。

上一篇
源文件检测配置
下一篇
v3到v4迁移指南（二）：配置迁移