Tailwind CSS v3 与 v4：生成机制、源码扫描和迁移实践

引言

Tailwind CSS 通过组合 utility class 编写界面样式。理解 v3 与 v4 的生成方式，有助于维护旧项目、配置源码扫描并规划升级。本文只讨论可从官方文档核对的版本差异，不把下载量、性能百分比或路线图预测当作技术结论。

Utility-first 与构建阶段生成

Tailwind 的类名表达单项或少量样式属性，例如 p-4、text-lg 和 hover:bg-blue-700。这些类通常直接出现在模板中，构建工具扫描源码后生成项目使用到的 CSS。

Tailwind CSS v3 把 JIT 生成作为默认方式，并使用 content 配置列出模板和组件路径：

// tailwind.config.js (v3)
module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx,vue}'],
  theme: { extend: {} },
  plugins: [],
};

因此，旧项目中的 mode: 'jit' 和 purge 配置应按 v3 的配置格式检查，不能和其他版本的配置混为一谈。

v4 的 CSS 优先配置与 Oxide

Tailwind CSS v4 改用 Oxide 引擎，并把常见配置放到 CSS 入口中：

@import "tailwindcss";

@theme {
  --color-brand-600: #1769aa;
  --spacing-page: 1.5rem;
}

v4 支持自动源检测；未被自动发现的模板或组件库可通过 @source 登记：

@source "../packages/ui/src";

Oxide 改变的是构建工具链。Tailwind CSS 仍然在开发或生产构建过程中生成样式，页面不会因为用了 v4 就在浏览器中即时编译，也不因此消除构建步骤。

动态类名和设计 token

扫描器需要在源码中看到完整候选。不要把片段拼成可能未出现于文件中的类名：

const buttonClasses = {
  primary: 'bg-blue-600 hover:bg-blue-700 text-white',
  muted: 'bg-slate-100 text-slate-900',
};

为颜色、间距等共享值建立 token，有助于保持组件一致。v3 项目可使用 theme.extend；v4 项目可使用 @theme。迁移时应按项目版本选择其中一种方式，避免同时维护两套相互冲突的定义。

@apply 可以把重复的 utility 组合放进 CSS 组件规则，但它不会自动让 CSS 更小。只有在重复代码或组件边界更清楚时才使用，并通过构建产物验证实际变化。

升级时逐项验证

1. 记录当前 Tailwind、Node.js、PostCSS 和框架版本。
2. 阅读v3 发布说明、v4 发布说明与官方升级指南。
3. 按版本核对扫描路径、插件、动态类名和 CSS 入口。
4. 在代表性页面检查响应式、hover/focus、暗色主题和动态状态。
5. 对照锁文件和生产构建产物，记录已知差异并保留可回退版本。

源码扫描规则与额外目录配置可参考Detecting classes in source files。如果项目稳定运行在 v3，是否升级应由支持需求、依赖兼容性和维护成本决定，而不是单纯追逐版本号。性能体积的测量流程见Tailwind CSS 生产样式体积优化。