在 Webpack 构建流程中引入 PurgeCSS 来删除项目里没有被用到的 CSS 类名，是前端优化包体积的常见手段。但很多工程在配置之后，页面样式突然出现错乱，追查下来才发现是某些类在构建阶段被错误地判定为“未使用”而遭到移除。这种现象并不是 PurgeCSS 本身的 bug，而是静态分析机制与动态语言特性之间的天然矛盾。理解这些矛盾点，才能安全地享受 tree-shaking 样式带来的好处。
静态提取机制为何会误删动态类名
PurgeCSS 的核心工作原理是：根据你配置的 content 文件列表，提取出所有文件中的字符串字面量，再用正则表达式匹配其中看起来像类名的部分，最后拿这些“疑似使用集合”与 CSS 文件中的选择器做差集，删掉差集里的规则。这个过程完全发生在构建期，它不会执行你的 JavaScript，也不会分析变量运行时的值。因此，任何不是以纯字符串字面量形式出现在源码里的类名，都很可能逃过扫描。
例如下面这段 React 代码，按钮的类名是根据 props 里的 type 动态拼接的。源码里只出现了字符串 'btn-' 和变量插值，并没有完整的 'btn-primary' 或 'btn-danger' 文本。PurgeCSS 扫描时只能看到 btn- 这个片段，无法推断出完整类名，于是对应的 CSS 规则就会被当作无用代码清除。
function Button({ type, children }) {
const cls = 'btn-' + type;
return <button className={cls}>{children}</button>;
}
解决这类问题不能靠修改业务代码去迎合工具，而是要在 PurgeCSS 的 safelist 配置中显式声明这些动态模式。你可以使用正则表达式保护所有以 btn- 开头的类，这样无论运行时怎么拼接，构建产物都会保留它们。同时要注意，safelist 写得过于宽泛（比如直接放行所有类）会失去优化意义，需要结合项目实际动态类名规律来收敛范围。
content 路径覆盖不全导致整片样式消失
另一个高频陷阱是 content 配置项没有包含所有可能引用类名的文件。PurgeCSS 只会扫描你明确告诉它的文件，如果你漏掉了某些 html 模板、ejs 文件或者动态加载的视图组件，那么这些文件里用到的类就不会进入“使用集合”，对应 CSS 自然被删光。在 Webpack 多入口或者微前端架构里，子应用的模板常常被主构建忽略，问题尤其隐蔽。
下面是一段典型的 purgecss-webpack-plugin 配置。很多开发者只写了 src/*.js，却忘了把 public 里的 html 和组件里的模板字符串文件加进去。当你的类名其实写在 index.html 的 body 结构上时，仅仅扫描 js 是找不到它们的。
const PurgeCSSPlugin = require('purgecss-webpack-plugin');
const glob = require('glob');
const path = require('path');
module.exports = {
plugins: [
new PurgeCSSPlugin({
paths: glob.sync([
path.resolve(__dirname, 'src/**/*.js'),
path.resolve(__dirname, 'public/**/*.html'),
path.resolve(__dirname, 'src/**/*.ejs')
], { nodir: true }),
safelist: [/btn-/]
})
]
};
建议把 content 的 glob 规则打印出来人工核对一次，确认每一个挂载了 DOM 结构的文件类型都在内。如果项目用了类似 innerHTML 赋值大段 HTML 字符串的方式渲染，也要保证包含这些字符串的 js 或 ts 文件被扫描。只有路径闭环了，移除未使用 CSS 才不会出现“误伤友军”。
第三方组件库与 CSS Modules 的冲突处理
当项目里引入了 Element UI、Ant Design 这类带独立样式的组件库，并且你希望对它们也做瘦身时，PurgeCSS 可能会把库内部依赖的运行时类名删掉。这些库经常在 JS 里通过 style 或者动态 class 映射来切换状态，源码中未必有静态完整的类名文本。此外，如果开启了 CSS Modules，本地化的类名在编译后变成哈希字符串，而 PurgeCSS 扫描的是编译前的源文件，匹配逻辑很容易错位。
面对组件库，通常更稳妥的方案是改用官方提供的按需加载（如 babel-plugin-import），而不是用 PurgeCSS 去砍库样式。如果一定要全局扫，需要在 safelist 里加入第三方前缀，比如 /^el-/、/^ant-/。对于 CSS Modules，可以配置 modules 选项让 PurgeCSS 识别本地标识符，或干脆只对全局样式文件启用插件，避免干扰模块化样式。
new PurgeCSSPlugin({
paths: glob.sync(path.resolve(__dirname, 'src/**/*.{js,jsx,ts,tsx}'), { nodir: true }),
safelist: {
standard: [/^el-/, /^ant-/],
greedy: [/^local_/]
}
});
总的来说，PurgeCSS 在 Webpack 中是一把双刃剑。它能有效删除冗余 CSS，但前提是你能清楚回答三个问题：动态类名怎么保护、扫描路径是否完整、第三方样式如何处理。把这三个陷阱理顺之后，再配合构建后的视觉回归测试，就能在包体积和样式安全之间拿到平衡。