PurgeCSS如何自动删除生产环境中的冗余CSS代码？

本文共计958个文字，预计阅读时间需要4分钟。

基本原理并非错误判断，而是它默认只扫描 ``、`js`、`jsx`、`vue` 等文件中的字符串——动态拼接的类名、运行时生成的类、或通过 JS 注入的 class（如 `el.classList.add('hidden')`）——它本质上视而不见。

• 常见错误现象：hidden、active、is-open 这类通用工具类突然失效
• 使用场景：React/Vue 中用变量拼接 class（className={`btn ${type}-btn`}），或 Tailwind 的 @apply + 动态值
• 解决方法必须显式告诉 PurgeCSS 哪些内容要保留：content 配置里加 glob 路径，或用 defaultExtractor 自定义提取逻辑
• 别依赖“扫描整个项目”，太慢还容易漏；优先写明确的 content 数组，例如：['./src/**/*.{js,ts,jsx,tsx,vue}']

PurgeCSS 和 PostCSS 插件顺序错位导致白屏

如果你在 postcss.config.js 里把 purgecss 放在 autoprefixer 或 cssnano 后面，就可能出问题：前者删类，后者压缩时又把已删掉的选择器相关声明合并/优化，最终产出空规则或损坏的 CSS。

• 正确顺序永远是：postcss-import → tailwindcss（如有）→ purgecss → autoprefixer → cssnano
• 尤其注意 cssnano 的 discardUnused 默认为 true，和 PurgeCSS 功能重叠，建议关掉：{ discardUnused: false }
• Vite 用户要检查 vite-plugin-purgecss 是否与 vite-plugin-css-injected-by-js 冲突——后者注入的 CSS 不在 PurgeCSS 的 content 范围内，直接被清空

Tailwind 项目里 PurgeCSS 报 “No files found” 错误

这通常不是路径写错，而是 PurgeCSS 在构建早期阶段执行，此时 Vite/Rollup/Webpack 还没把 .vue 或 .tsx 编译成带 class 字符串的 JS，它扫了个寂寞。

• 检查 content 里的 glob 是否匹配实际输出路径（比如 Vite 的 dist 下没有源码，不能配 ./src/**/*.vue）
• Vite 用户应改用 vite-plugin-purgecss，它在转换后钩子中运行；Webpack 用户用 purgecss-webpack-plugin，别手写 new PurgeCSSPlugin()
• 如果用了 content 数组里混了注释或空字符串，PurgeCSS 会静默跳过——确保每项都是有效 glob 或绝对路径
• Windows 下路径分隔符问题：用 path.join(__dirname, 'src', '**', '*.{js,ts}') 比硬写 ./src/**/*.js 更稳

class 名带方括号或特殊字符时 PurgeCSS 失效

Tailwind 的 [@media](screen)、[&_svg]、[data-theme="dark"] 这类写法，原始 PurgeCSS 提取器不认识，直接忽略。

立即学习“前端免费学习笔记（深入）”；

• 必须启用 keyframes: true 和 fontFace: true（即使不用动画/字体，有些插件依赖它识别语法）
• 对 [data-*] 类型，需在 safelist 里加正则：/^data-/；对 [&_xxx]，得靠 defaultExtractor 扩展匹配逻辑
• 别指望 safelist 里写 '[data-theme="dark"]' 就行——双引号会被当字面量，实际 CSS 里是没引号的；应写 /^data-theme$/ 或更宽松的 /data-.*/

最麻烦的其实是框架组件库的 class：它们往往不写死在模板里，而是由 JS 控制。这种没法靠扫描解决，只能老老实实加 safelist，而且得覆盖所有变体，比如 /^el-.*$/ 或 ['el-button', 'el-input', 'el-select__caret']。