Tailwind CSS v4 迁移完全指南：新引擎、CSS-first 配置与性能飞跃

前端工程（更新于 2026年5月4日）

Tailwind CSS v4：重新定义原子化 CSS

v4 不是渐进升级，而是架构重写——新引擎（Oxide）带来 10x 构建速度，CSS-first 配置取代 JS 配置。

维度 v3 v4
引擎 PostCSS 插件 Rust 引擎 (Oxide)
配置 tailwind.config.js CSS @theme 指令
内容检测 content 数组 自动检测
构建速度 基准 10x+
容器查询 插件 原生支持
3D 变换 插件 原生支持

一、新引擎：Oxide

性能对比

操作 v3 v4 提升
全量构建 (1000+ 工具类) ~500ms ~50ms 10x
增量 HMR ~50ms ~5ms 10x
大型项目 (500+ 组件) ~2s ~200ms 10x

Oxide 使用 Rust 编写，通过 Wasm 或原生模块集成到构建工具中。

二、CSS-first 配置

v3：JS 配置文件

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [require('@tailwindcss/typography')],
};

v4：CSS 配置

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

@theme {
  --color-brand: #3b82f6;
  --font-sans: "Inter", sans-serif;
  --breakpoint-xs: 475px;
  --spacing-18: 4.5rem;
}

优势：

  • 配置即 CSS，IDE 原生支持
  • 无需 JS 运行时
  • 更容易与设计系统对齐

自定义工具类

@theme {
  --animate-fade-in: fade-in 0.3s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(-10px); }
  to { opacity: 1; transform: translateY(0); }
}

<div class="animate-fade-in">淡入效果</div>

三、自动内容检测

v4 不再需要手动配置 content 数组，自动从项目结构推断：

框架 检测方式
Next.js 自动扫描 app/、src/
Vite 自动扫描 src/
Nuxt 自动扫描 components/、pages/
通用 自动扫描项目根目录

如需排除路径：

@import "tailwindcss" source("../src");
/* 或排除 */
@import "tailwindcss" source("../src") not("../src/generated");

四、原生容器查询支持

v3 需要插件

plugins: [require('@tailwindcss-container-queries')]
// <div class="md:max-w-sm"> → @container

v4 原生支持

<div class="@container">
  <div class="@md:flex-row flex-col">
    容器宽度 >= md 时水平布局
  </div>
</div>

@theme {
  --container-md: 448px;
}
容器查询类 含义
@container 定义容器
@sm:flex-row 容器 >= sm 时 flex-row
@md:grid-cols-2 容器 >= md 时两列
@lg:hidden 容器 >= lg 时隐藏

五、3D 变换原生支持

<div class="rotate-x-45 rotate-y-30 rotate-z-15
            perspective-500 translate-z-10
            scale-3d scale-x-110 scale-y-90">
  3D 变换元素
</div>
类名 CSS 属性
rotate-x-45 rotateX(45deg)
rotate-y-30 rotateY(30deg)
rotate-z-15 rotateZ(15deg)
perspective-500 perspective(500px)
translate-z-10 translateZ(10px)
scale-3d scale3d()
backface-hidden backface-visibility: hidden

六、迁移步骤

步骤一：升级依赖

npm install tailwindcss@next @tailwindcss/postcss@next

步骤二：更新 PostCSS 配置

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

步骤三：迁移配置文件

/* app.css - 新配置 */
@import "tailwindcss";

/* 迁移 v3 的 theme.extend */
@theme {
  /* colors */
  --color-primary: #3b82f6;
  --color-secondary: #10b981;

  /* fontFamily */
  --font-sans: "Inter", "system-ui", sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* spacing */
  --spacing-18: 4.5rem;

  /* breakpoints */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

步骤四：处理 Breaking Changes

v3 写法 v4 写法 说明
bg-opacity-50 bg-blue-500/50 透明度修饰符
ring-offset-blue-500 ring-offset-blue-500 移除的类需检查
overflow-ellipsis text-ellipsis 更名
scale-50 (0.5) scale-50 (0.5) 不变
blur-sm (4px) blur-sm (4px) 不变
shadow-outline 自定义 已移除

步骤五：移除不再需要的插件

插件 v4 替代
@tailwindcss/container-queries 原生支持
@tailwindcss/3d 原生支持
@tailwindcss/line-clamp 原生支持 (line-clamp-3)

七、Vite 集成

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';

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

不再需要 PostCSS 中间件——Vite 插件直接集成，速度更快。

八、常见迁移陷阱

1. 自定义颜色不生效

/* 错误：缺少 --color- 前缀 */
@theme {
  --brand: #3b82f6;  /* 不会生成 text-brand, bg-brand */
}

/* 正确 */
@theme {
  --color-brand: #3b82f6;  /* 生成 text-brand, bg-brand, border-brand */
}

2. @apply 行为变化

/* v3: @apply 可以使用任意工具类 */
/* v4: @apply 仅支持静态工具类，不支持动态值 */

.button {
  @apply bg-blue-500 text-white;  /* ✅ */
  @apply bg-[#123456];            /* ❌ 改用直接写 CSS */
}

3. 前缀模式变化

/* v3: prefix 在 JS 配置中 */
/* v4: prefix 在 CSS 中 */
@import "tailwindcss" prefix(tw);
/* 生成 tw-flex, tw-text-lg 等 */

九、推荐迁移策略

  1. 新项目直接用 v4：零迁移成本
  2. 现有项目渐进迁移：v3 和 v4 可共存于不同入口
  3. 先迁移配置：将 JS 配置转为 CSS @theme
  4. 再处理 Breaking Changes：使用官方 codemod
  5. 最后移除插件：替换为原生功能
# 官方 codemod
npx @tailwindcss/upgrade@next
#Tailwind CSS#CSS#前端框架#迁移