Tailwind CSS v4 迁移指南：从 v3 升级到 v4 的完整实战

原创。读完本文，你将掌握 Tailwind CSS v4 的核心变化，了解配置方式从 tailwind.config.js 到 @import "tailwindcss" 的演进，并能按照迁移清单将现有 v3 项目升级到 v4。

前言

2025 年初，Tailwind CSS v4.0 正式发布。这不仅是版本号的更新——它从底层重新设计了整个框架。配置方式、构建工具、自定义主题的方式都发生了根本性变化。

如果你还在用 v3，看到 v4 的配置方式可能会感到陌生：postcss.config.js 不见了？tailwind.config.js 去哪了？自定义颜色写在 CSS 文件里？

这篇文章将带你逐步了解 v4 的所有变化，并给出从 v3 迁移到 v4 的完整操作指南。

Tailwind CSS v4 的核心变化

1. 配置革命：从 JS 配置到 CSS 原生

v4 最大的变化是 抛弃了 tailwind.config.js。所有配置都通过 CSS 原生的 @ 指令来完成。

v3 时代（旧方式）：

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

v4 时代（新方式）：

/* app.css - 这就是全部的 Tailwind 配置 */
@import "tailwindcss";
 
/* 自定义主题色 */
@theme {
  --color-brand: #3b82f6;
}
 
/* 自定义断点 */
@theme {
  --breakpoint-xs: 30rem;
}

这个变化的好处是显而易见的：你不再需要来回切换 CSS 和 JS 配置文件。所有样式相关的配置都在一个 CSS 文件中完成，前端工程师的工作流更加顺畅。

2. 自动内容检测

v4 默认会自动扫描项目中的模板文件，不再需要手动配置 content 数组。它通过检测项目中的常见文件类型（.html、.jsx、.tsx、.vue、.php 等）来自动确定扫描范围。

如果你的项目结构特殊，可以通过 @config 指令指定配置文件：

@import "tailwindcss";
@config "./tailwind.config.custom.js";

3. 全新的构建管线

v4 不再依赖 PostCSS 作为唯一的构建方式。它现在是一个独立的 CSS 引擎，支持多种接入方式：

Vite 项目的最简配置：

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

/* src/style.css */
@import "tailwindcss";

就这么简单。不再需要 postcss.config.js，不再需要 tailwind.config.js，一行 CSS import 就够了。

4. 新增实用类

v4 引入了大量新的实用类，以下是其中最值得关注的：

尺寸与布局：

• size-{n} — 同时设置 width 和 height 的简写，size-6 等价于 w-6 h-6
• inset-* 系列的更多变体
• field-sizing-content — 让输入框根据内容自动调整大小

颜色与渐变：

• 全新的调色板（更鲜艳、更现代）
• 改进的渐变工具，支持多步色标
• random-{color} — 随机色，适合快速原型

交互：

• group-hover、group-focus 等群组选择器性能大幅优化
• 3D 变换支持更全面

动画：

• 内置动画数量翻倍
• 支持 CSS 原生 @starting-style 和 transition-behavior: allow-discrete
• 新的 animate-enter 和 animate-exit 系列

5. 首屏性能优化

v4 生成的 CSS 文件体积比 v3 平均减少 35%。这是因为新的引擎在编译时做了更激进的 tree-shaking，只生成项目中实际用到的样式。

对于大型项目，这个优化效果非常明显。比如一个包含 200+ 组件的 React 项目，v3 生成的 CSS 约 180KB（gzip 后 28KB），v4 可以减少到 110KB（gzip 后 17KB）。

从 v3 迁移到 v4 的完整步骤

第一步：评估影响

v4 不是一个无痛升级。核心破坏性变更包括：

1. tailwind.config.js 被废弃 — 所有主题配置需要改写到 CSS 的 @theme 中
2. @apply 行为变化 — v4 中 @apply 只能用于 CSS 类中，且支持更严格的校验
3. 层叠规则改变 — @layer 的使用方式不同
4. 一些旧类名被移除或重命名 — 如 overflow-clip、overflow-ellipsis 等

第二步：创建迁移分支

git checkout -b upgrade-tailwind-v4

第三步：更新依赖

# 移除旧版本
npm uninstall tailwindcss postcss autoprefixer
 
# 安装 v4 及相关插件（根据你的构建工具选择）
npm install tailwindcss @tailwindcss/postcss
# 或：npm install tailwindcss @tailwindcss/vite
# 或：npm install tailwindcss @tailwindcss/cli

第四步：迁移 PostCSS 配置

v3 的 PostCSS 配置（需要移除）：

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

v4 的最简配置（如果你仍用 PostCSS）：

// postcss.config.js
module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

注意，v4 不再需要 autoprefixer——它已经内置在引擎中。

第五步：迁移主题配置

这是最费时的一步。对照你的 tailwind.config.js，把所有 theme.extend 中的配置迁移到 CSS 中。

颜色迁移示例：

// v3 tailwind.config.js
theme: {
  extend: {
    colors: {
      primary: {
        50: '#eff6ff',
        500: '#3b82f6',
        900: '#1e3a5f',
      },
    },
  },
}

/* v4 app.css */
@import "tailwindcss";
 
@theme {
  --color-primary-50: #eff6ff;
  --color-primary-500: #3b82f6;
  --color-primary-900: #1e3a5f;
}

字体配置迁移：

// v3
theme: {
  extend: {
    fontFamily: {
      sans: ['Inter', 'system-ui', 'sans-serif'],
    },
  },
}

/* v4 */
@theme {
  --font-family-sans: 'Inter', 'system-ui', 'sans-serif';
}

第六步：检查 @apply 用法

v4 对 @apply 更严格，不允许在媒体查询或 @layer 中使用。如果你有类似这样的代码：

/* v3 中可能可以工作，v4 会报错 */
@media (min-width: 768px) {
  .my-class {
    @apply flex items-center;
  }
}

需要改成：

/* v4 的正确方式 */
.my-class {
  @apply flex items-center;
}
 
@media (min-width: 768px) {
  .my-class {
    @apply md:flex md:items-center;
  }
}

第七步：构建验证

# 重新构建项目
npm run build
 
# 检查是否有编译错误或警告

常见问题：

• ❌ '@tailwind base' → 改为 @import "tailwindcss"
• ❌ tailwind.config.js not found → 所有配置转移到 CSS @theme
• ❌ 自定义插件无法加载 → 使用 @plugin 指令替代 JS 插件 API

迁移清单速查

什么时候应该升级？什么时候应该等？

建议现在升级的情况：

• 新建项目 → 直接用 v4，配置量减少 60% 以上
• 小项目（< 20 个页面）→ 迁移工作量小，一两天能搞定
• 重度使用多主题 / CSS 变量的项目 → v4 的 @theme 体系比 v3 的 JS 配置灵活得多

建议等等的情况：

• 大型项目（> 100 个组件）→ 全面检查所有 @apply 和自定义插件的兼容性，建议等第三方 UI 库（如 daisyUI、shadcn/ui）同步支持 v4 后再迁移
• 广泛使用 Tailwind 插件的项目 → 检查插件作者是否已更新到 v4

总结

Tailwind CSS v4 代表了框架演进的一个重要方向：更少的配置文件，更多的 CSS 原生能力。将配置从 JavaScript 搬到 CSS 变量的做法，让样式定义更加直观，也让框架与现代 CSS 标准趋势保持一致。

虽然 v3 迁移到 v4 需要一些手动工作，但只要按本文的迁移清单逐步操作，大多数项目都能在 1-2 天内完成升级。而升级后获得的更小构建体积、更快的开发体验和更简洁的配置，会让这次迁移非常值得。

参考来源：Tailwind CSS v4 官方发布公告 | LogRocket Tailwind CSS 指南