Tailwind CSS 生产样式体积优化：内容扫描与可复现验证

引言

Tailwind CSS 的生产样式体积取决于版本、扫描到的源码、插件和构建配置，不能用一个固定压缩比例代表所有项目。本文按 Tailwind CSS v3 与 v4 分别说明内容扫描、动态类名和体积验证方法。核心目标是让构建结果可复现，而不是承诺某个统一的 KB 数或 LCP 增幅。

先建立可比较的构建基线

优化前先记录 Node.js、Tailwind CSS、框架和构建工具版本，执行生产构建，并保存 CSS 文件大小及 gzip 或 Brotli 后的传输大小。比较时使用相同的提交、构建命令和压缩方式；一次只改变一个变量。

npm ci
npm run build
find dist -type f -name '*.css' -exec wc -c {} +
gzip -c dist/assets/app.css | wc -c

文件大小只能描述资源体积。首屏表现还受 HTML、图片、字体、缓存、网络和设备影响；如需评估用户体验，应另用 Lighthouse 或真实用户数据比较 LCP、INP 等指标，并写清测试环境和样本范围。

Tailwind CSS v3：检查 content 扫描范围

在 v3 中，content 列表应覆盖实际包含 Tailwind 类名的模板和组件文件。无需启用 mode: 'jit'，JIT 已是 v3 的默认生成方式。

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

扫描范围过宽会让构建检查更多文件；范围过窄则会漏掉模板中的类名。先从仓库结构确认实际入口，再运行生产构建检查结果。只有类名确实由运行时数据决定、且无法静态列出时，才用 safelist 指定允许的完整类名；不要用宽泛正则掩盖扫描配置错误。

Tailwind CSS v4：核对自动源检测

v4 使用新的 Oxide 引擎和 CSS 优先的配置方式。它仍在构建阶段生成 CSS，不是浏览器运行时编译，也不会自动取消项目的构建步骤。一般从主 CSS 文件导入框架：

@import "tailwindcss";

@theme {
  --color-brand-600: #1769aa;
}

v4 会自动检测常见源码；如果组件库或模板目录没有被检测到，可用 @source 显式登记：

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

升级时不要把 v3 的 purge 或 mode: 'jit' 配置原样搬到 v4。先阅读官方升级指南，逐个核对插件、浏览器支持和构建工具是否兼容，再比较构建产物。

动态类名要让完整候选可见

源码扫描器读取的是文件文本。下面这种拼接可能让扫描器无法发现最终类名：

const className = `bg-${color}-600`;

把每种状态写成完整类名更可靠：

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

这样既能让扫描器识别候选，也方便代码审查状态集合。类似的内容扫描和版本差异可继续参考Tailwind CSS 技术演进与版本实践。

上线前的核对顺序

1. 固定依赖锁文件和生产构建命令。
2. 核对模板、组件库和服务端模板是否在扫描范围内。
3. 检查动态状态是否使用完整类名，必要时只 safelist 明确清单。
4. 对比 CSS 原始大小与压缩传输大小，并检查构建产物中关键页面样式。
5. 在目标设备和网络条件下单独测量页面体验，不从 CSS 文件变化直接推导排名或转化结果。

Tailwind 优化的有效证据是项目自身可重复的构建和页面测试。没有测试记录时，应描述配置和验证步骤，不把演示数字写成通用结论。