CSS PurgeCSS 未使用样式剔除、Safelist 机制与 Minification 配合实践

一、问题概述：未使用 CSS 的积累与动态类名失误

大型应用中未使用的样式会增加网络传输与浏览器解析开销。PurgeCSS 扫描源码模板提取 token 来匹配 CSS 选择器；然而对于 const cls = 'status-' + type 这类动态类名，静态正则无法感知运行时完整值，容易将 .status-active 作为废弃代码剔除。

二、最小复现：动态拼接类名在摇树后丢样式

当源码通过字符串拼接动态决定类名时，PurgeCSS 仅扫描出单独的 token，若无 Safelist 配置，打包产物中的对应规则会被移除。

<!-- 源码中的动态样式逻辑 -->
<script>
  const type = 'danger';
  const className = 'alert-' + type;
</script>

/* PurgeCSS 会保留 .alert 或 .danger (若存在)，但无法匹配动态生成的 .alert-danger 规则 */
.alert-danger { background-color: #f8d7da; color: #721c24; }

三、根因：字面量 Extractor 的局限性

PurgeCSS 默认使用正则表达式提取源码中的字符串 token（如 /[A-Za-z0-9_-]+/g）。它只做文本扫描，不执行 JavaScript 运行时逻辑，因此无法计算变量拼接或条件计算后产生的字面量。

四、推荐方案：Safelist 白名单防护与 Minification & 缓存协作

1. 显式配置 Safelist：支持精确匹配、正则表达式前缀匹配（如 /^alert-/）及深度匹配。2. 源码中书写完整类名映射字典而非模糊拼接。3. 优化流水线协作：PurgeCSS 清理未使用规则 -> Minifier 压缩体积 -> 配合 ContentHash 与 HTTP 强缓存（Cache-Control: max-age=31536000, immutable）。

五、完整代码：模拟简单的 CSS Selector Extractor 与 Safelist 过滤

下面的 TypeScript 代码示范如何提取源码 Token，并结合 Safelist 白名单判断指定 CSS 选择器是否应该被保留。

interface PurgeOptions {
  safelist: (string | RegExp)[];
}

function extractTokens(sourceCode: string): Set<string> {
  const words = sourceCode.match(/[A-Za-z0-9_-]+/g) ?? [];
  return new Set(words);
}

function isSelectorRetained(selector: string, usedTokens: Set<string>, options: PurgeOptions): boolean {
  const classNames = selector.match(/\.[A-Za-z0-9_-]+/g)?.map((c) => c.slice(1)) ?? [];
  if (classNames.length === 0) return true;

  return classNames.every((className) => {
    const inSafelist = options.safelist.some((rule) => {
      if (typeof rule === "string") return rule === className;
      return rule.test(className);
    });
    if (inSafelist) return true;

    return usedTokens.has(className);
  });
}

const htmlSource = '<div class="btn main-title">Hello</div>';
const tokens = extractTokens(htmlSource);
const options: PurgeOptions = { safelist: [/^alert-/] };

console.log(isSelectorRetained(".btn", tokens, options)); // true (匹配模板 token)
console.log(isSelectorRetained(".alert-danger", tokens, options)); // true (匹配 Safelist 正则)
console.log(isSelectorRetained(".card-hidden", tokens, options)); // false (未引用且无 Safelist 匹配)

六、常见错误方案

将字符串拼接写在代码注释里尝试欺骗 Extractor；把整个 UI 框架的所有类名全部加入 Safelist 导致 Tree-shaking 彻底失效；在开发环境启动 PurgeCSS 导致热更新样式频繁丢失。

七、边界条件：CSS 原生变量、伪元素与动态 DOM

原生 CSS 变量 (--theme-color) 和由第三方 SDK 动态插入到 document.body 的全局类名无法被静态模版提取，必须手工添加至 Safelist 或保留模式中。

八、如何验证 Purge 后的样式完整性

对生产产物运行 E2E 视觉回归；覆盖动态类名、条件分支、富文本与第三方组件，并断言关键选择器仍存在于最终 CSS。

九、FAQ

问：PurgeCSS 与 CSS Minify 有何区别？答：PurgeCSS 负责剔除根本没用到的完整选择器规则；CSS Minify 负责去除保留代码中的空白、注释并优化语法。

问：Safelist 是否支持正则表达式？答：支持，推荐使用正则表达式匹配具有统一前缀的动态类名（如 /^btn-/）。

问：Tailwind CSS v3+ 如何处理未使用样式？答：Tailwind v3+ 采用 JIT 实时编译引擎，按需生成代码，无需额外配置 PurgeCSS。

十、总结

PurgeCSS 摇树剔除与 Minification 压缩是互补的样式瘦身手段。理清 Extractor 的词法匹配边界并合理配置 Safelist 白名单，能在获得显著体积压缩的同时保障动态样式安全。