liveBlog
首页
CSS2025-01-01
返回首页

Tailwind CSS v4 升级手记

Tailwind CSS v4 升级手记

Tailwind CSS v4 在 2025 年初发布正式版，变化比预期的大。如果你在考虑升级，这篇文章可能会帮到你。

最大的变化：配置方式

v4 最大的改变是配置方式。不再用 tailwind.config.js，改成了 CSS-first 的配置：

/* 以前的 tailwind.config.js */
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: '#ff6b6b',
      },
    },
  },
};

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

@theme {
  --color-brand: #ff6b6b;
  --font-sans: "Inter", sans-serif;
}

配置直接写在 CSS 文件里，用 CSS 自定义属性来定义。这个改动挺大的，意味着之前积累的 tailwind.config.js 需要迁移。

新的引擎

Tailwind v4 用 Oxide 引擎重写了，用 Rust 写的。速度提升非常大，在大型项目里差异尤其明显。

我测试了一个有 500+ 组件文件的项目：

  • v3 全量构建：8.2 秒
  • v4 全量构建：1.3 秒

热更新也快了很多，几乎感觉不到延迟。

CSS 变量集成

v4 原生支持 CSS 自定义属性作为主题变量：

@theme {
  --color-primary: oklch(0.7 0.15 200);
  --color-secondary: oklch(0.8 0.1 300);
}

然后用 bg-primary、text-secondary 这样的类名直接使用。CSS 变量的好处是可以在运行时动态修改，不需要重新编译。

暗色模式也更简单了：

@theme {
  --color-bg: #ffffff;
  --color-text: #1a1a1a;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #1a1a1a;
    --color-text: #ffffff;
  }
}

不需要 dark: 前缀，直接用 CSS 变量就行。当然 dark: 变体仍然可用，两种方式可以混用。

自动内容检测

v4 不再需要 content 配置来指定哪些文件包含 Tailwind 类名。它会自动检测，类似 purgecss 的扫描方式。

这个改动省了不少配置工作，尤其是 monorepo 项目里不用再维护冗长的 content 路径列表。

新增的实用功能

容器查询

<div class="@container">
  <div class="@sm:flex @sm:gap-4">
    <div class="@sm:w-48">...</div>
    <div>...</div>
  </div>
</div>

用 @container 替代之前的插件配置，开箱即用。

3D 变换

<div class="perspective-500 rotate-x-12 rotate-y-6">
  <div class="transform-3d translate-z-20">...</div>
</div>

v4 内置了完整的 3D 变换工具类，不需要自己写自定义样式。

颜色混合

@theme {
  --color-brand-50: color-mix(in oklch, var(--color-brand) 10%, white);
  --color-brand-100: color-mix(in oklch, var(--color-brand) 20%, white);
}

用 color-mix() 自动生成色阶，不用手动算每个颜色值。

迁移指南

从 v3 升级到 v4

  1. 安装 v4：npm install tailwindcss@4

  2. 替换 PostCSS 配置：

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

// postcss.config.js（现在）
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

注意：v4 不再需要 autoprefixer，已经内置了。

  1. 迁移配置：把 tailwind.config.js 里的主题配置搬到 CSS 文件里

  2. 处理破坏性变更：

    • bg-opacity-* 改为 bg-[color]/[opacity] 语法
    • 一些不常用的工具类被移除或重命名
    • 插件 API 有变化，第三方 Tailwind 插件需要更新

升级的风险

  • 大部分第三方 Tailwind 插件还没适配 v4
  • 如果你依赖 @apply 大量使用，可能需要调整
  • UI 组件库（如 shadcn/ui）的 Tailwind 集成可能需要更新

我的建议

如果你在用 Tailwind v3：

  • 新项目可以直接用 v4
  • 老项目不急的话可以再等等，等生态更成熟一些再迁移
  • 如果你对构建速度有要求，v4 值得现在就升级

v4 的核心方向是更快、更简洁、更原生。虽然配置方式变了需要迁移，但用起来确实比 v3 方便。

CSSTailwindCSS
返回首页