PurgeCSS会删除button__icon类名,因其默认不解析BEM分隔符__和--,且未配置content、extractors或safelist正则覆盖BEM模式,导致动态拼接或JSX中的类名漏扫,引发样式断裂。

为什么PurgeCSS会删掉button__icon这类BEM类名
PurgeCSS默认只识别标准 CSS 类名,button__icon里的双下划线__和双短横--被当作普通字符处理,不触发 BEM 语义解析。结果就是:button__icon被当成未引用字符串漏扫,icon又可能从button__icon里被切出来单独匹配,误判为独立类名而保留——造成样式断裂或冗余残留。
必须配置content和extractors才能扫到JSX/TSX里的BEM类名
React/Vue项目中,BEM类名常拼在className里,PurgeCSS默认不解析 JSX/TSX 语法,必须显式告诉它去哪里找:
-
content字段至少包含src/**/*.{ts,tsx,js,jsx},不能只写src/**/*.js - Vue用户要配
extractors处理<template>块,否则<button class="btn btn--primary">完全不被识别 - Vite等工具默认输出
dist/index.html,但PurgeCSS只读源码,不读构建产物,路径写错就漏扫
safelist正则必须覆盖BEM分隔符模式
仅靠content扫描还不够,运行时动态拼接的类名(如classNames('card', isFeatured ? 'card--featured' : ''))可能漏掉。这时得用safelist兜底:
- 写正则时明确包含
__和--,例如/^card(__|--).*/或/^[a-z]+(__|--)[a-z]+$/ - 避免宽泛匹配:
/card/会把cart、discard也带上,增加无效体积 - 如果用了
important: false,又手写了.card__header { padding: 1rem; },这条规则大概率被p-4覆盖且无警告
BEM类名必须和HTML实际渲染严格一致
PurgeCSS只保留 HTML 中“显式出现”的class字符串,任何 JS 运行时拼接、服务端渲染漏传、Web Component shadow DOM 里的类名,都可能被误删:
立即学习“前端免费学习笔记(深入)”;
- SSR场景下,若用户首次访问是亮色模式,
body--dark从未出现在 HTML 中,对应 CSS 极大概率被构建阶段删光 - 用
document.createElement('div').className = 'card__footer'动态插入,PurgeCSS根本看不到这个字符串 - 测试环境没跑全交互路径(比如没点开 modal),
modal__overlay--visible这种条件类名就会被当死代码删掉
__、漏一条safelist、content路径差一级,都会让样式在生产环境突然消失。


















