Tailwind CSS v4：有哪些变化，为什么值得关注

新的构建引擎

Tailwind CSS v4 重新设计了构建引擎，并采用 CSS 优先配置。构建性能取决于项目、集成和缓存状态。在把提速归因于升级前，应在自己的仓库中测量这些条件。

速度只是一部分。v4 更明显的方向变化是以 CSS 为中心的配置。

CSS 优先配置

v4 可以通过 @theme 直接在 CSS 中定义设计变量。为兼容旧项目，显式用 @config 加载时，仍支持 JavaScript 配置：

@import 'tailwindcss';

@theme {
  --color-bg-primary: #0d1117;
  --color-bg-secondary: #161b22;
  --color-accent-teal: #00adb5;
  --color-accent-rose: #e2725b;

  --font-heading: 'Poppins', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 4px 24px rgba(0, 0, 0, 0.3);
}

这种方式有几项好处：

1. 减少上下文切换：设计变量就是 CSS 自定义属性，其他工具也能读取。
2. 集中管理：配置与样式可以一起评审。
3. 编辑器支持：CSS 文件拥有语法高亮、补全和验证。
4. 可组合：通过标准 var() 语法引用其他变量。

从 v3 迁移时，@tailwindcss/upgrade 命令行工具能自动处理大部分转换，读取 JavaScript 配置并生成相应的 @theme 内容。

如何组织设计变量

在 Rosecraft Studios，我们按语义类别组织 @theme：

@theme {
  /* === Colors === */
  --color-bg-primary: #0d1117;
  --color-bg-secondary: #161b22;
  --color-bg-card: #131920;

  --color-accent-teal: #00adb5;
  --color-accent-rose: #e2725b;
  --color-text-primary: #e6edf3;
  --color-text-muted: #8b949e;

  /* === Typography === */
  --font-heading: 'Poppins', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;

  /* === Shadows === */
  --shadow-card: 0 4px 24px rgba(0, 0, 0, 0.3);
  --shadow-teal-glow: 0 4px 16px rgba(0, 173, 181, 0.25);
}

组件随后引用变量名称，而不是直接写十六进制颜色值：

<div className="bg-bg-card border border-border rounded-lg p-6">
  <h3 className="font-heading text-text-primary text-xl font-semibold">Card Title</h3>
  <p className="font-body text-text-muted">Card description</p>
</div>

当客户要求调整主题时，这种做法很方便。把 --color-accent-teal 从 #00adb5 改成 #0891b2，引用该变量的组件会一起更新，无需逐处搜索替换。

自动检测内容

Tailwind v4 不再要求配置 content 数组，新引擎会自动检测哪些文件使用工具类：

/* v3: Required explicit content paths */
/* content: ['./src/**/*.{js,ts,jsx,tsx}'] */

/* v4: Just import and it works */
@import 'tailwindcss';

自动检测存在排除项，包括忽略文件和依赖。可用 @source 注册额外目录，例如 monorepo 中的共享组件：

@import 'tailwindcss';
@source "../shared/components";
@source "./src";

内置容器查询

v4 原生支持容器查询，让布局依据可用容器空间变化：

<div className="@container">
  <div className="@sm:flex @sm:gap-4 @md:grid @md:grid-cols-3">
    {/* Layout responds to container width, not viewport */}
  </div>
</div>

容器查询尤其适合组件库。卡片可以根据分配到的空间调整布局，无论它被放在页面的哪个位置。

如何测量升级

迁移前后记录干净构建时间、代表性修改后的重新构建时间、生成 CSS 大小和峰值内存。使用相同机器及依赖，多次测量，并将结果保存在拉取请求中。编译器变快，不会自动让访客页面也变快。

需要留意的不兼容变化

迁移并非完全无缝，重点检查以下方面。

工具类和配置变化

查看官方升级指南，确认阴影和圆角类的重命名、ring 默认值，以及浏览器要求。选择有代表性的页面进行视觉检查，覆盖焦点、悬停和响应式状态。

旧插件与 CSS 工具类

@plugin 用来加载旧式 JavaScript 插件，并不是把 JavaScript 的 plugin() 助手替换成 CSS 文件加载器：

@import 'tailwindcss';
@plugin '@tailwindcss/typography';

用 CSS 定义工具类时，使用 @utility：

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

详细内容见指令参考。

深色模式

dark 变体默认使用 prefers-color-scheme。若要由 .dark 类控制，可以覆盖变体：

@import 'tailwindcss';
@custom-variant dark (&:where(.dark, .dark *));

参见 Tailwind 深色模式文档。

规划迁移

先检查浏览器支持和插件兼容性，在独立分支运行升级工具，评审生成的变更，再比较关键布局与交互状态。将迁移视作一次代码和视觉评审，并留出排查回归问题的时间。

需要 Tailwind v4 迁移或设计系统开发支持？联系我们，讨论您的项目与迁移风险。