Tailwind CSS v4 新特性全面解读与迁移实战

Tailwind CSS v4 在 2025 年正式发布，这个版本带来了全新的配置引擎、更快的构建速度和更好的 CSS 原生特性集成。对于正在使用 Tailwind v3 的项目，本文提供了完整的迁移指南和最佳实践。

v4 核心变化

1. CSS-first 配置：告别 tailwind.config.js，使用原生 CSS 的 @theme 指令定义设计系统。

@theme { --color-primary: #3b82f6; --font-size-heading: 2rem; --spacing-section: 4rem; }

2. 基于 Lightning CSS 的构建系统：构建性能提升 10 倍以上。一个大型项目的 CSS 编译时间从 3.2 秒降至 0.28 秒。

3. 原生 CSS Cascade Layers 集成：自动使用 @layer 管理样式优先级，完美解决第三方组件样式覆盖问题。

迁移步骤

1. 升级 Tailwind 包到 v4，运行 npx @tailwindcss/upgrade 自动迁移工具。

2. 将 tailwind.config.js 中的 theme 配置迁移到 CSS 的 @theme 指令。

3. 检查自定义插件，v4 的插件 API 有少量 breaking changes。

4. 移除不再需要的 @tailwind 指令，v4 使用原生的 CSS import。

新功能亮点

v4 新增了同级选择器变体（sibling-*）、改进的容器查询集成、以及自动化的暗色模式切换。此外，内联主题变量使得组件库可以更优雅地暴露自定义样式属性。