Tailwind CSS v4 迁移指南：新特性与破坏性变更

Tailwind CSS v4 是一次从头开始的重写，带来了显著更快的构建、简化的配置体验和现代 CSS 优先的方法。从 v3 迁移到 v4 需要理解新架构、更新的配置模式和破坏性变更。

Tailwind CSS v4 的新特性

Tailwind CSS v4 不仅仅是增量更新，而是使用名为 Oxide 的新引擎完全重写，基于 Rust 构建，性能大幅提升。最明显的变化是从 JavaScript 配置转向 CSS 优先配置。

性能改进

新的 Oxide 引擎比 v3 提供高达 10 倍的完整构建速度和 100 倍的增量构建速度。热模块替换几乎是即时的。

CSS 优先配置

Tailwind v4 使用 @theme、@variant 和 @utility 指令将配置移入 CSS 文件中，消除了大多数项目对 tailwind.config.js 的需求。

/* Tailwind v4: CSS-first configuration */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --font-display: "Inter", sans-serif;
  --font-body: "Source Sans 3", sans-serif;
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --radius-lg: 12px;
  --spacing-18: 4.5rem;
}

/* Custom utilities */
@utility text-balance {
  text-wrap: balance;
}

/* Custom variants */
@variant hocus (&:hover, &:focus);
@variant theme-dark (.dark &);

现代 CSS 特性

Tailwind v4 利用现代 CSS 特性，包括级联层、容器查询、锚点定位、color-mix() 和广色域颜色。

迁移步骤

按照以下步骤将项目从 Tailwind CSS v3 迁移到 v4。

步骤 1：更新依赖

安装最新的 Tailwind CSS v4 包，如果使用 Vite 则移除 PostCSS 插件。

# Run the automated upgrade tool (recommended)
npx @tailwindcss/upgrade

# Or manually update dependencies
npm install tailwindcss@latest

# For Vite projects, install the Vite plugin
npm install @tailwindcss/vite

# Remove the PostCSS plugin (if using Vite)
npm uninstall @tailwindcss/postcss autoprefixer

# vite.config.ts
import tailwindcss from "@tailwindcss/vite";

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

步骤 2：更新 CSS 入口文件

将 @tailwind 指令替换为新的 @import 语法。在 v4 中，你将 Tailwind 作为 CSS 模块导入。

/* v3 (old) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 (new) */
@import "tailwindcss";

/* That single import replaces all three directives */
/* Tailwind automatically detects your source files */

步骤 3：将 tailwind.config.js 迁移到 CSS

使用 @theme 将主题自定义从 tailwind.config.js 移到 CSS 文件中。

/* v3: tailwind.config.js */
// module.exports = {
//   theme: {
//     extend: {
//       colors: {
//         brand: '#3b82f6',
//         accent: '#f59e0b',
//       },
//       fontFamily: {
//         display: ['Inter', 'sans-serif'],
//       },
//       spacing: {
//         '18': '4.5rem',
//       },
//     },
//   },
// }

/* v4: CSS configuration */
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --color-accent: #f59e0b;
  --font-display: "Inter", sans-serif;
  --spacing-18: 4.5rem;
}

/* Use in templates: bg-brand, text-accent, font-display, mt-18 */

步骤 4：更新类名

一些工具类名在 v4 中已更改。检查模板中已弃用或重命名的类。

<!-- Renamed utilities in v4 -->

<!-- Shadow color: shadow-[color] -> shadow-[color]/opacity -->
<!-- v3 --> <div class="shadow-lg shadow-blue-500/50">
<!-- v4 --> <div class="shadow-lg shadow-blue-500/50">  <!-- same -->

<!-- Ring offset: ring-offset-2 ring-offset-blue-500 -->
<!-- Now uses outline utilities in some cases -->

<!-- Blur: backdrop-blur-sm -> backdrop-blur-sm  (unchanged) -->

<!-- Gradient stops are the same but color syntax may differ -->
<!-- v3 --> <div class="bg-gradient-to-r from-blue-500 to-purple-500">
<!-- v4 --> <div class="bg-linear-to-r from-blue-500 to-purple-500">

<!-- Content classes renamed -->
<!-- v3 --> <div class="content-center">
<!-- v4 --> <div class="place-content-center">

<!-- Decoration renamed -->
<!-- v3 --> <div class="decoration-2">
<!-- v4 --> <div class="decoration-2">  <!-- unchanged -->

破坏性变更

Tailwind v4 包含几个需要在迁移期间解决的破坏性变更。

v4 新特性

容器查询

Tailwind v4 内置了 CSS 容器查询支持，允许根据父容器大小而非视口来设置元素样式。

<!-- Container queries in Tailwind v4 -->
<div class="@container">
  <div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3">
    <div class="@sm:p-4 @md:p-6">
      Responds to container width, not viewport
    </div>
  </div>
</div>

<!-- Named containers -->
<div class="@container/sidebar">
  <div class="@md/sidebar:flex-row">
    Content adapts to sidebar width
  </div>
</div>

颜色混合

新的颜色混合工具类使用 CSS color-mix() 混合颜色，无需在主题中定义即可创建色调变化。

<!-- Color mixing in v4 -->
<div class="bg-blue-500/50">50% opacity blue</div>
<div class="bg-mix-blue-500-white-30">30% white mixed into blue</div>

/* oklch colors in theme */
@theme {
  --color-brand-50: oklch(0.97 0.02 250);
  --color-brand-100: oklch(0.93 0.04 250);
  --color-brand-500: oklch(0.6 0.2 250);
  --color-brand-900: oklch(0.3 0.15 250);
}

深色模式改进

v4 中的深色模式默认使用 prefers-color-scheme 媒体查询，可通过 @variant 指令自定义。

/* Dark mode with system preference (default in v4) */
<div class="bg-white dark:bg-gray-900">
  Automatic dark mode based on OS preference
</div>

/* Class-based dark mode */
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

/* Now use: <html class="dark"> to toggle */

Custom Utilities in v4

Tailwind v4 makes creating custom utilities simpler with the @utility directive. You can define utilities directly in CSS without writing a JavaScript plugin.

/* Custom utilities in v4 */
@utility text-balance {
  text-wrap: balance;
}

@utility content-auto {
  content-visibility: auto;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

/* Custom utility with variants */
@utility glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

/* Usage in templates */
/* <div class="text-balance glass scrollbar-hidden"> */
/* <div class="hover:glass dark:glass"> */

Quick Reference: v3 to v4 Changes

// Configuration changes summary
// v3: tailwind.config.js    -> v4: @theme in CSS
// v3: @tailwind base         -> v4: @import "tailwindcss"
// v3: content: [...]         -> v4: auto-detection
// v3: plugins: [...]         -> v4: @plugin "..." or @utility

// PostCSS setup
// v3: postcss.config.js with @tailwindcss/postcss
// v4: Vite plugin (recommended) or @tailwindcss/postcss

// Source detection
// v4 automatically scans:
// - All .html, .jsx, .tsx, .vue, .svelte files
// - Ignores node_modules, .git, dist
// - Configure with @source directive if needed:
// @source "../other-project/src/**/*.tsx";

迁移最佳实践

• 首先运行自动迁移工具：npx @tailwindcss/upgrade
• 一次迁移一个组件，而非整个项目
• 使用浏览器开发工具比较迁移前后的渲染样式
• 在升级前检查并更新自定义插件到新 API
• 彻底测试响应式断点
• 检查颜色使用，因为 v4 默认使用 oklch 色彩空间
• 将 IDE 扩展更新到最新版本以获得 v4 自动补全支持

常见问题