前端构建工具【免费下载链接】purgecssRemove unused CSS项目地址https://gitcode.com/gh_mirrors/pu/purgecss点击查看免费下载PurgeCSS 是当前仓库monorepo的核心项目其使命只有一句话Remove unused CSS移除未使用的 CSS。本指南以仓库根目录的 README.md 为骨架完整讲解 PurgeCSS 的安装、编程式 API、CLI、配置选项、Safelisting 与 Extractors 机制并结合 packages/purgecss/src/index.ts 等源码揭示底层实现原理。读完本文你将掌握如何在任何构建流程中接入 PurgeCSS把最终交付的 CSS 体积压到最小同时避免误删仍在使用中的样式。PurgeCSS 是什么问题与解决方案在构建网站时绝大多数项目都会引入 CSS 框架例如 Bootstrap、Materializecss、Foundation 等。但实际项目中往往只用到框架的一小部分能力大量未被使用的 CSS 样式会一并打包进最终产物白白增加页面体积、拖慢加载速度。PurgeCSS 正是为解决这一问题而生。它的工作方式非常直观分析内容文件content读取 HTML、JS、Vue、Pug 等文件提取其中实际出现的 CSS 选择器标签、类名、ID、属性名等分析 CSS 文件css解析需要清理的样式表匹配与清除把 CSS 中的选择器与内容文件中出现的选择器做匹配凡是内容中没有出现的选择器对应的规则就会被移除最终输出更小的 CSS 文件。整个过程可以在构建阶段自动完成无需人工维护哪些样式在用的清单。从源码看这一匹配逻辑集中在PurgeCSS类的shouldKeepSelector()方法中packages/purgecss/src/index.ts它对每个 CSS 选择器逐一判断只有出现在提取结果集ExtractorResultSets中的 class、id、tag、attribute 才会被保留。安装与快速上手安装把 PurgeCSS 安装为开发依赖即可npm install purgecss --save-dev安装完成后即可在 JavaScript / TypeScript 项目中直接调用其编程式 API。基础用法README 给出了最小可用的调用示例通过PurgeCSS类的purge()方法传入content内容文件 glob和cssCSS 文件 globpurge()返回清理后的结果数组。import { PurgeCSS } from purgecss; const purgeCSSResults await new PurgeCSS().purge({ content: [**/*.html], css: [**/*.css], });这是 ES Module 的写法如果使用 CommonJS则等价于const { PurgeCSS } require(purgecss); const purgeCSSResult await new PurgeCSS().purge({ content: [**/*.html], css: [**/*.css], });purge()返回的purgeCSSResults是一个数组每个元素对应一份被清理的 CSS 文件形如[ { file: main.css, css: /* purged css for main.css */, }, { file: animate.css, css: /* purged css for animate.css */, }, ];对应的类型定义是ResultPurge见 docs/api.mdinterface ResultPurge { css: string; file?: string; rejected?: string[]; rejectedCss?: string; }当启用了rejected或rejectedCss选项时结果中还会额外携带被移除选择器或整段被移除 CSS 的信息。核心工作流程从文件到净化后的 CSSpurge()的内部调用链可以从源码中得到完整印证packages/purgecss/src/index.ts合并选项将用户传入的选项与defaultOptions合并safelist会被standardizeSafelist()标准化为统一结构提取文件型内容调用extractSelectorsFromFiles()对content中的文件路径/glob 逐一读取并用对应的 extractor 提取选择器提取原始字符串内容调用extractSelectorsFromString()处理content中形如{ raw, extension }的原始字符串合并提取结果通过mergeExtractorSelectors()把两类提取结果合并为一个ExtractorResultSets遍历 CSS调用getPurgedCSS()对每份 CSS 用 PostCSS 解析成 AST再经walkThroughCSS()逐节点评估、删除未使用规则最后按需执行removeUnusedFontFaces()、removeUnusedKeyframes()、removeUnusedCSSVariables()三项收尾清理。其中walkThroughCSS()packages/purgecss/src/index.ts是核心遍历器对rule节点调用evaluateRule()做选择器级评估对atrule节点调用evaluateAtRule()登记 keyframes / font-face对comment节点识别purgecss start ignore/purgecss end ignore注释以切换忽略状态。值得注意的细节是evaluateRule()中对:where()与:is()的处理第一轮遍历会移除其中未使用的选择器但保留伪类本身第二轮再移除已被清空、只剩空:where/:is的选择器packages/purgecss/src/index.ts。同时空规则无选择器或无数值会被自动删除避免产出残留的空壳。配置选项详解完整、可复制的配置示例与类型定义位于 docs/configuration.md。defaultOptions的实际默认值可以在 packages/purgecss/src/options.ts 中查到css、content、extractors、safelist、blocklist、skippedContentGlobs、dynamicAttributes默认为空数组/空对象fontFace、keyframes、rejected、rejectedCss、sourceMap、stdin、stdout、variables默认为falsedefaultExtractor默认匹配所有由字母、数字、下划线、连字符组成的词。content指定要分析的内容文件content接收一个由文件名或 glob 模式组成的数组文件可以是 HTML、Pug、Blade、JS、Vue 等任何可能包含选择器的文件await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], });除了文件路径PurgeCSS 也支持原始内容传入带raw属性的对象即可。若希望自定义 extractor 能正确匹配还需同时传入extension属性await new PurgeCSS().purge({ content: [ { raw: htmlbodydiv classapp/div/body/html, extension: html, }, **/*.js, **/*.html, **/*.vue, ], css: [ { raw: body { margin: 0 }, }, css/app.css, ], });从extractSelectorsFromFiles()的实现packages/purgecss/src/index.ts可以看到PurgeCSS 会先尝试把条目当作真实文件直接读取失败后再用glob.sync展开 glob若 glob 展开后仍没有任何文件会输出一条警告No files found from the passed PurgeCSS option content.方便排查路径写错的问题。css指定要清理的样式表与content类似css同样接收文件名或 glob 数组也支持{ raw: ... }形式的原始 CSSawait new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], });await new PurgeCSS().purge({ content: [ { raw: htmlbodydiv classapp/div/body/html, extension: html, }, ], css: [ { raw: body { margin: 0 }, }, ], });在getPurgedCSS()packages/purgecss/src/index.ts中字符串形式的 css 条目同样先经 glob 展开再按文件读取除非启用stdin每条 CSS 都会独立产出{ css, file }结果并支持sourceMap、rejected、rejectedCss等附加字段。defaultExtractor为所有文件设置默认提取器如果发现大量未使用的 CSS 未被移除即提取不够充分可以为所有类型的文件统一指定一个自定义 extractorawait new PurgeCSS().purge({ // ... defaultExtractor: (content) content.match(/[\w-/:](?!:)/g) || [], });defaultOptions中的默认 extractor 是content.match(/[A-Za-z0-9_-]/g) || []它把文件中的每个词都当作潜在选择器但不会识别、:、/等特殊字符详见 docs/extractors.md 对默认 extractor 局限性的说明。当getFileExtractor()找不到与文件扩展名匹配的 extractor 时就会回退到defaultExtractorpackages/purgecss/src/index.ts。extractors按文件扩展名精确提取如果希望不同扩展名使用不同 extractor可以用extractors选项按扩展名注册import purgeFromHTML from purge-from-html; await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], extractors: [ { extractor: purgeFromHTML, extensions: [html], }, { extractor: (content) content.match(/[\w-/:](?!:)/g) || [], extensions: [vue, js], }, ], });getFileExtractor()会按文件后缀名匹配extractors数组中第一个命中项。官方文档建议把 extractor 视为一种高级优化手段它们能带来更好的准确率但行为因实现而异可能更难推理并非所有项目都需要。更多内容见 docs/extractors.md。fontFace默认 false若 CSS 中存在未被使用的font-face规则可开启此选项移除它们await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], fontFace: true, });源码层面evaluateAtRule()会收集所有font-face中的font-family名称packages/purgecss/src/index.tscollectDeclarationsData()则收集实际用到的font-family值最后removeUnusedFontFaces()删除未被引用的规则packages/purgecss/src/index.ts。font-face的收集与清理测试可见 packages/purgecss/tests/font-faces.test.ts。keyframes默认 false如果使用了 animate.css 这类动画库可以开启此选项移除未使用的 keyframesawait new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], keyframes: true, });实现上collectDeclarationsData()会从animation/animation-name声明中收集动画名packages/purgecss/src/index.tsevaluateAtRule()把以keyframes结尾的 at-rule 登记为待清理对象removeUnusedKeyframes()最终删除未被引用、且未被safelist.keyframes放行的 keyframespackages/purgecss/src/index.ts。variables默认 false如果项目使用 CSS 自定义属性Custom Properties即 CSS 变量或使用了 Bootstrap 这类依赖 CSS 变量的库可开启此选项移除未使用的 CSS 变量await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], variables: true, });实现由VariablesStructure类承担packages/purgecss/src/VariablesStructure.ts它记录每个--*变量的定义位置与所有var(...)引用removeUnusedCSSVariables()调用variablesStructure.removeUnused()完成清理。相关测试见 packages/purgecss/tests/css-variables.test.ts。rejected默认 false与 rejectedCss默认 false调试时扫描被移除的列表往往能快速发现误删或异常await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], rejected: true, });开启后结果对象的rejected字段会包含所有被移除的选择器selectorsRemoved集合见 packages/purgecss/src/index.ts。对应的测试用例见 packages/purgecss/tests/rejected.test.ts。如果希望保留被丢弃的整段 CSS 用于审计或双版本发布则用rejectedCssawait new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], rejectedCss: true, });开启后evaluateRule()会把每条规则中被移除的选择器重组为克隆规则并存入removedNodespackages/purgecss/src/index.ts最终通过rejectedCss字段以整段 CSS 字符串形式返回packages/purgecss/src/index.ts。测试见 packages/purgecss/tests/rejectedCss.test.ts。safelist指定必须保留的选择器safelist用于声明哪些选择器是安全的、必须留在最终 CSS 中。它有两种形式。简单形式——字符串与正则的数组safelist: [random, yep, button, /^nav-/];复杂形式——对象结构safelist: { standard: [random, yep, button, /^nav-/], deep: [], greedy: [], keyframes: [], variables: [] }例如const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: [random, yep, button], });此时.random、#yep、button三个选择器会留在最终 CSS 中注意字符串会同时匹配 class、id 与标签名三种形态。再如const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: [/red$/], });所有以red结尾的选择器如.bg-red都会被保留。safelist在源码中的标准化逻辑由standardizeSafelist()完成数组形式会被展开为{ standard: [...] }并补齐其他字段的默认值对象形式则与默认结构做浅合并packages/purgecss/src/index.ts。此外isSelectorSafelisted()还会检查一份内部安全名单CSS_SAFELISTpackages/purgecss/src/internal-safelist.ts以及::开头的伪元素这些会被默认保留。safelist.deep连同子选择器一起保留safelist.deep按正则匹配选择器并同时保留其所有后代选择器const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: { deep: [/red$/], }, });此例中即使child-of-bg在内容中从未出现.bg-red .child-of-bg也会被完整保留。实现对应isSelectorSafelistedDeep()packages/purgecss/src/index.ts只要某个选择器片段命中deep正则整条规则立即保留。safelist.greedy任意片段命中即整条保留safelist.greedy更激进只要选择器的任意一部分命中正则整条选择器就保留const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: { greedy: [/red$/], }, });例如button.bg-red.nonexistent-class即使button与nonexistent-class都未在内容中出现也会被保留。实现对应isSelectorSafelistedGreedy()它会在shouldKeepSelector()里把选择器拆成多个片段逐一比对packages/purgecss/src/index.ts、packages/purgecss/src/index.ts。相关测试覆盖了 children 与 greedy 两种模式见 packages/purgecss/tests/safelist.test.ts。blocklist强制移除选择器blocklist与 safelist 相反即使某个选择器被 extractor 判定为已使用只要命中 blocklist仍会被强制移除blocklist: [usedClass, /^nav-/];即使nav-links和usedClass都被 extractor 提取到它们仍会被删除。对应isSelectorBlocklisted()packages/purgecss/src/index.ts且 blocklist 的优先级高于保留判断——在shouldKeepSelector()中命中 blocklist 的选择器会直接返回false。测试见 packages/purgecss/tests/safelist.test.tsblocklist 用例。skippedContentGlobs跳过不需要扫描的文件当content使用 glob 时可以用skippedContentGlobs排除某些文件或目录skippedContentGlobs: [node_modules/**, components/**];此时 PurgeCSS 不会扫描node_modules与components两个目录。注意当content不是 glob而是具体文件路径时此选项不生效。源码在 glob 展开阶段直接把这些模式透传给glob.sync的ignore参数packages/purgecss/src/index.ts。dynamicAttributes自定义动态属性用于补充aria-selected、data-selected这类自定义动态属性选择器dynamicAttributes: [aria-selected];实现上属性选择器在匹配时会额外检查dynamicAttributes列表以及value、checked、selected、open这四个默认动态属性——因为它们依赖用户交互状态无法从静态内容中可靠推断所以默认总是保留packages/purgecss/src/index.ts。配置文件purgecss.config.js除了直接传选项对象PurgeCSS 也支持读取配置文件。默认配置文件名是purgecss.config.js常量CONFIG_FILENAME见 packages/purgecss/src/constants.ts它是一个普通的 JavaScript 文件module.exports { content: [index.html], css: [style.css], };然后可以在代码中以两种方式使用const purgecss await new PurgeCSS().purge(); // 或把配置文件路径作为唯一参数传入 const purgecss await new PurgeCSS().purge(./purgecss.config.js);setOptions()packages/purgecss/src/index.ts会基于process.cwd()解析并动态import配置文件加载失败时抛出带有 Error loading the config file 前缀的错误错误常量见 packages/purgecss/src/constants.ts。CLI 的--config选项走的也是同一套加载逻辑。命令行界面CLIPurgeCSS 同时提供 CLI既可直接使用也可搭配配置文件使用。先安装全局或作为 devDependency 后配合npx均可npm i -g purgecss运行purgecss --help可查看全部选项Usage: purgecss --css css... --content content... [options] Remove unused css selectors Options: -V, --version output the version number -con, --content files... glob of content files -css, --css files... glob of css files -c, --config path path to the configuration file -o, --output path file path directory to write purged css files to -font, --font-face option to remove unused font-faces -keyframes, --keyframes option to remove unused keyframes -v, --variables option to remove unused variables -rejected, --rejected option to output rejected selectors -rejected-css, --rejected-css option to output rejected css -s, --safelist list... list of classes that should not be removed -b, --blocklist list... list of selectors that should be removed -k, --skippedContentGlobs list... list of glob patterns for folders/files that should not be scanned -h, --help display help for commandCLI 选项与配置文件选项一一对应CLI 入口源码见 packages/purgecss/src/bin.ts基于commander解析参数。--csspurgecss --css css/app.css css/palette.css --content src/index.html--content--content接受多个文件名或 glob 模式文件类型不限HTML、Pug、Blade 等purgecss --css css/app.css --content src/index.html src/**/*.js--config使用配置文件时用-c/--config指定路径purgecss --config ./purgecss.config.js--output默认情况下 CLI 把结果输出到控制台需要落盘时用--output指定输出目录purgecss --css css/app.css --content src/index.html src/**/*.js --output build/css/--safelist防止某个选择器被移除时把它加入 safelistpurgecss --css css/app.css --content src/index.html --safelist classnameToSafelist更完整的 CLI 用法与输出文件测试见 packages/purgecss/tests/cli 下的测试文件包括控制台输出cli-console-output.test.ts、单文件输出cli-file-output.test.ts、多文件输出cli-multiple-files-output.test.ts与选项解析cli-options.test.ts。在 CSS 中直接使用忽略注释Safelisting 进阶除了配置项还可以在 CSS 源码中通过特殊注释直接控制保留行为详见 docs/safelisting.md。使用/* purgecss ignore */保留下一条规则/* purgecss ignore */ h1 { color: blue; }使用/* purgecss ignore current */保留当前规则注释写在规则内部h1 { /* purgecss ignore current */ color: blue; }使用/* purgecss start ignore */与/* purgecss end ignore */保留一段连续范围/* purgecss start ignore */ h1 { color: blue; } h3 { color: green; } /* purgecss end ignore */ h4 { color: purple; }这些注释对应的常量与识别逻辑分别在 packages/purgecss/src/constants.ts 与isIgnoreAnnotation()、hasIgnoreAnnotation()packages/purgecss/src/index.ts中purgecss ignore下一条、purgecss ignore current当前规则内部、purgecss start ignore/purgecss end ignore范围开关。注释本身在处理完成后会被从输出中移除。一个重要的坑GotchasPostCSS、cssnano 等 CSS 优化工具在构建流程中可能先于 PurgeCSS 剥离注释导致忽略注释失效。由于这些步骤在开发模式下常常被跳过问题容易被忽视。解决办法是用感叹号把注释标记为重要注释/*! purgecss start ignore */ h5 { color: pink; } h6 { color: lightcoral; } /*! purgecss end ignore */这样压缩工具会保留它们PurgeCSS 仍能识别。Extractors提取器的机制与扩展PurgeCSS 依赖 extractor 从内容文件中获取使用了哪些选择器。HTML、Pug、JS 等不同类型的文件都可能包含选择器因此提取器需要按文件类型适配详见 docs/extractors.md。默认 extractor适用于所有文件类型但能力有限它把文件中的每个词都视为选择器不识别、:、/等特殊字符在复杂模板场景下可能提取不充分。自定义 extractor就是一个普通函数接收文件内容字符串返回选择器数组tags、classes、ids或返回结构更精细的对象interface ExtractorResultDetailed { attributes: { names: string[]; values: string[]; }; classes: string[]; ids: string[]; tags: string[]; undetermined: string[]; }const purgeFromJs (content) { // 返回 css selector 数组 };返回详细对象能让 PurgeCSS 获得更好的匹配精度在ExtractorResultSetspackages/purgecss/src/ExtractorResultSets.ts中这些结果被拆分到attrNames、attrValues、classes、ids、tags、undetermined六个集合里分别支撑属性名、属性值、类、ID、标签的精确匹配无法归类的词进入undetermined在各类匹配时兜底参与判断例如hasClass()会同时检查classes与undetermined。在配置中使用 extractor 的完整示例import { purgeCSSFromPug } from purgecss-from-pug; import { purgeCSSFromHtml } from purgecss-from-html; const options { content: [], // 用于提取选择器的文件 css: [], // css extractors: [ { extractor: purgeCSSFromPug, extensions: [pug], }, { extractor: purgeCSSFromHtml, extensions: [html], }, ], }; export default options;约定俗成的命名规则是purgecss-from-[文件类型]如purgecss-from-pug便于在 npm 上搜索同类提取器。仓库中已经实现并发布了多个提取器包purgecss-from-htmlpackages/purgecss-from-html、purgecss-from-jsxpackages/purgecss-from-jsx、purgecss-from-tsxpackages/purgecss-from-tsx、purgecss-from-pugpackages/purgecss-from-pug。官方文档提示这些提取器仍处于演进阶段生产环境使用前需自行评估。生态monorepo 中的包与插件当前仓库是一个用 Lerna 管理的 monorepo见根目录 lerna.json多个包从同一份代码库发布到 npm。README 列出的核心包如下各包详情可从 packages 目录进入Package说明purgecssPurgeCSS 的核心包包含分析文件、移除未使用 CSS 的核心方法postcss-purgecss面向 PostCSS 的 PurgeCSS 插件purgecss-webpack-plugin面向 Webpack 的 PurgeCSS 插件gulp-purgecss面向 Gulp 的 PurgeCSS 插件grunt-purgecss面向 Grunt 的 PurgeCSS 插件rollup-plugin-purgecss面向 Rollup 的 PurgeCSS 插件purgecss-from-htmlHTML 提取器purgecss-from-pugPug 提取器purgecss-with-wordpress面向 WordPress 的 safelist 集合vue-cli-plugin-purgecssVue CLI 插件绝大多数构建工具与框架都在使用 PostCSS因此最快上手 PurgeCSS 的方式是使用其 PostCSS 插件docs/plugins/postcss.mdnpm i -D fullhuman/postcss-purgecssconst purgecss require(fullhuman/postcss-purgecss); module.exports { plugins: [ purgecss({ content: [./**/*.html], }), ], };仓库还提供了面向各主流框架的接入指南可作为对应生态下的实战参考前端框架Vue.js、Nuxt.js、React.js、Next.js、Razzle静态站点与 CMSHugo、WordPress构建工具插件Webpack、Gulp、Grunt、Gatsby进一步阅读配置选项全解全部选项、类型定义与可复制示例命令行界面CLI 安装、参数与输出编程式 APIES Module / CommonJS 两种用法与返回结构Safelistingsafelist 各种形态与 CSS 内注释的完整说明Extractors默认提取器局限、自定义提取器与结果结构Comparison与其他同类工具/方案的对比核心实现packages/purgecss/src/index.ts 中的PurgeCSS类、shouldKeepSelector()、walkThroughCSS()以及 packages/purgecss/src/ExtractorResultSets.ts 中的选择器结果集赞分享前端构建工具【免费下载链接】purgecssRemove unused CSS项目地址https://gitcode.com/gh_mirrors/pu/purgecss点击查看免费下载相关推荐PurgeCSS 入门指南高效移除未使用的CSS样式PurgeCSS 入门指南高效移除未使用的CSS样式 什么是PurgeCSS PurgeCSS 是一款专门用于移除项目中未使用CSS的工具。在现代前端开发中前端构建工具PurgeCSS深度解析如何高效移除未使用的CSS样式PurgeCSS深度解析如何高效移除未使用的CSS样式 什么是PurgeCSS PurgeCSS是一款专门用于移除项目中未使用CSS代码的工具。在现代前端开发前端构建工具PurgeCSS 快速上手用 PostCSS 插件移除未使用 CSS 的完整指南PurgeCSS 快速上手用 PostCSS 插件移除未使用 CSS 的完整指南 本篇指南讲解在当前 PurgeCSS 仓库中推荐的快速入门路径通过 fu前端构建工具上一篇DeepSeek-Math 完整使用指南10个快速上手技巧 下一篇如何让老旧Mac焕发新生OpenCore Legacy Patcher完全解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PurgeCSS 完整指南：基于 content 与 CSS 匹配，系统性移除未使用的样式
前端构建工具【免费下载链接】purgecssRemove unused CSS项目地址https://gitcode.com/gh_mirrors/pu/purgecss点击查看免费下载PurgeCSS 是当前仓库monorepo的核心项目其使命只有一句话Remove unused CSS移除未使用的 CSS。本指南以仓库根目录的 README.md 为骨架完整讲解 PurgeCSS 的安装、编程式 API、CLI、配置选项、Safelisting 与 Extractors 机制并结合 packages/purgecss/src/index.ts 等源码揭示底层实现原理。读完本文你将掌握如何在任何构建流程中接入 PurgeCSS把最终交付的 CSS 体积压到最小同时避免误删仍在使用中的样式。PurgeCSS 是什么问题与解决方案在构建网站时绝大多数项目都会引入 CSS 框架例如 Bootstrap、Materializecss、Foundation 等。但实际项目中往往只用到框架的一小部分能力大量未被使用的 CSS 样式会一并打包进最终产物白白增加页面体积、拖慢加载速度。PurgeCSS 正是为解决这一问题而生。它的工作方式非常直观分析内容文件content读取 HTML、JS、Vue、Pug 等文件提取其中实际出现的 CSS 选择器标签、类名、ID、属性名等分析 CSS 文件css解析需要清理的样式表匹配与清除把 CSS 中的选择器与内容文件中出现的选择器做匹配凡是内容中没有出现的选择器对应的规则就会被移除最终输出更小的 CSS 文件。整个过程可以在构建阶段自动完成无需人工维护哪些样式在用的清单。从源码看这一匹配逻辑集中在PurgeCSS类的shouldKeepSelector()方法中packages/purgecss/src/index.ts它对每个 CSS 选择器逐一判断只有出现在提取结果集ExtractorResultSets中的 class、id、tag、attribute 才会被保留。安装与快速上手安装把 PurgeCSS 安装为开发依赖即可npm install purgecss --save-dev安装完成后即可在 JavaScript / TypeScript 项目中直接调用其编程式 API。基础用法README 给出了最小可用的调用示例通过PurgeCSS类的purge()方法传入content内容文件 glob和cssCSS 文件 globpurge()返回清理后的结果数组。import { PurgeCSS } from purgecss; const purgeCSSResults await new PurgeCSS().purge({ content: [**/*.html], css: [**/*.css], });这是 ES Module 的写法如果使用 CommonJS则等价于const { PurgeCSS } require(purgecss); const purgeCSSResult await new PurgeCSS().purge({ content: [**/*.html], css: [**/*.css], });purge()返回的purgeCSSResults是一个数组每个元素对应一份被清理的 CSS 文件形如[ { file: main.css, css: /* purged css for main.css */, }, { file: animate.css, css: /* purged css for animate.css */, }, ];对应的类型定义是ResultPurge见 docs/api.mdinterface ResultPurge { css: string; file?: string; rejected?: string[]; rejectedCss?: string; }当启用了rejected或rejectedCss选项时结果中还会额外携带被移除选择器或整段被移除 CSS 的信息。核心工作流程从文件到净化后的 CSSpurge()的内部调用链可以从源码中得到完整印证packages/purgecss/src/index.ts合并选项将用户传入的选项与defaultOptions合并safelist会被standardizeSafelist()标准化为统一结构提取文件型内容调用extractSelectorsFromFiles()对content中的文件路径/glob 逐一读取并用对应的 extractor 提取选择器提取原始字符串内容调用extractSelectorsFromString()处理content中形如{ raw, extension }的原始字符串合并提取结果通过mergeExtractorSelectors()把两类提取结果合并为一个ExtractorResultSets遍历 CSS调用getPurgedCSS()对每份 CSS 用 PostCSS 解析成 AST再经walkThroughCSS()逐节点评估、删除未使用规则最后按需执行removeUnusedFontFaces()、removeUnusedKeyframes()、removeUnusedCSSVariables()三项收尾清理。其中walkThroughCSS()packages/purgecss/src/index.ts是核心遍历器对rule节点调用evaluateRule()做选择器级评估对atrule节点调用evaluateAtRule()登记 keyframes / font-face对comment节点识别purgecss start ignore/purgecss end ignore注释以切换忽略状态。值得注意的细节是evaluateRule()中对:where()与:is()的处理第一轮遍历会移除其中未使用的选择器但保留伪类本身第二轮再移除已被清空、只剩空:where/:is的选择器packages/purgecss/src/index.ts。同时空规则无选择器或无数值会被自动删除避免产出残留的空壳。配置选项详解完整、可复制的配置示例与类型定义位于 docs/configuration.md。defaultOptions的实际默认值可以在 packages/purgecss/src/options.ts 中查到css、content、extractors、safelist、blocklist、skippedContentGlobs、dynamicAttributes默认为空数组/空对象fontFace、keyframes、rejected、rejectedCss、sourceMap、stdin、stdout、variables默认为falsedefaultExtractor默认匹配所有由字母、数字、下划线、连字符组成的词。content指定要分析的内容文件content接收一个由文件名或 glob 模式组成的数组文件可以是 HTML、Pug、Blade、JS、Vue 等任何可能包含选择器的文件await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], });除了文件路径PurgeCSS 也支持原始内容传入带raw属性的对象即可。若希望自定义 extractor 能正确匹配还需同时传入extension属性await new PurgeCSS().purge({ content: [ { raw: htmlbodydiv classapp/div/body/html, extension: html, }, **/*.js, **/*.html, **/*.vue, ], css: [ { raw: body { margin: 0 }, }, css/app.css, ], });从extractSelectorsFromFiles()的实现packages/purgecss/src/index.ts可以看到PurgeCSS 会先尝试把条目当作真实文件直接读取失败后再用glob.sync展开 glob若 glob 展开后仍没有任何文件会输出一条警告No files found from the passed PurgeCSS option content.方便排查路径写错的问题。css指定要清理的样式表与content类似css同样接收文件名或 glob 数组也支持{ raw: ... }形式的原始 CSSawait new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], });await new PurgeCSS().purge({ content: [ { raw: htmlbodydiv classapp/div/body/html, extension: html, }, ], css: [ { raw: body { margin: 0 }, }, ], });在getPurgedCSS()packages/purgecss/src/index.ts中字符串形式的 css 条目同样先经 glob 展开再按文件读取除非启用stdin每条 CSS 都会独立产出{ css, file }结果并支持sourceMap、rejected、rejectedCss等附加字段。defaultExtractor为所有文件设置默认提取器如果发现大量未使用的 CSS 未被移除即提取不够充分可以为所有类型的文件统一指定一个自定义 extractorawait new PurgeCSS().purge({ // ... defaultExtractor: (content) content.match(/[\w-/:](?!:)/g) || [], });defaultOptions中的默认 extractor 是content.match(/[A-Za-z0-9_-]/g) || []它把文件中的每个词都当作潜在选择器但不会识别、:、/等特殊字符详见 docs/extractors.md 对默认 extractor 局限性的说明。当getFileExtractor()找不到与文件扩展名匹配的 extractor 时就会回退到defaultExtractorpackages/purgecss/src/index.ts。extractors按文件扩展名精确提取如果希望不同扩展名使用不同 extractor可以用extractors选项按扩展名注册import purgeFromHTML from purge-from-html; await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], extractors: [ { extractor: purgeFromHTML, extensions: [html], }, { extractor: (content) content.match(/[\w-/:](?!:)/g) || [], extensions: [vue, js], }, ], });getFileExtractor()会按文件后缀名匹配extractors数组中第一个命中项。官方文档建议把 extractor 视为一种高级优化手段它们能带来更好的准确率但行为因实现而异可能更难推理并非所有项目都需要。更多内容见 docs/extractors.md。fontFace默认 false若 CSS 中存在未被使用的font-face规则可开启此选项移除它们await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], fontFace: true, });源码层面evaluateAtRule()会收集所有font-face中的font-family名称packages/purgecss/src/index.tscollectDeclarationsData()则收集实际用到的font-family值最后removeUnusedFontFaces()删除未被引用的规则packages/purgecss/src/index.ts。font-face的收集与清理测试可见 packages/purgecss/tests/font-faces.test.ts。keyframes默认 false如果使用了 animate.css 这类动画库可以开启此选项移除未使用的 keyframesawait new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], keyframes: true, });实现上collectDeclarationsData()会从animation/animation-name声明中收集动画名packages/purgecss/src/index.tsevaluateAtRule()把以keyframes结尾的 at-rule 登记为待清理对象removeUnusedKeyframes()最终删除未被引用、且未被safelist.keyframes放行的 keyframespackages/purgecss/src/index.ts。variables默认 false如果项目使用 CSS 自定义属性Custom Properties即 CSS 变量或使用了 Bootstrap 这类依赖 CSS 变量的库可开启此选项移除未使用的 CSS 变量await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], variables: true, });实现由VariablesStructure类承担packages/purgecss/src/VariablesStructure.ts它记录每个--*变量的定义位置与所有var(...)引用removeUnusedCSSVariables()调用variablesStructure.removeUnused()完成清理。相关测试见 packages/purgecss/tests/css-variables.test.ts。rejected默认 false与 rejectedCss默认 false调试时扫描被移除的列表往往能快速发现误删或异常await new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], rejected: true, });开启后结果对象的rejected字段会包含所有被移除的选择器selectorsRemoved集合见 packages/purgecss/src/index.ts。对应的测试用例见 packages/purgecss/tests/rejected.test.ts。如果希望保留被丢弃的整段 CSS 用于审计或双版本发布则用rejectedCssawait new PurgeCSS().purge({ content: [index.html, **/*.js, **/*.html, **/*.vue], css: [css/app.css], rejectedCss: true, });开启后evaluateRule()会把每条规则中被移除的选择器重组为克隆规则并存入removedNodespackages/purgecss/src/index.ts最终通过rejectedCss字段以整段 CSS 字符串形式返回packages/purgecss/src/index.ts。测试见 packages/purgecss/tests/rejectedCss.test.ts。safelist指定必须保留的选择器safelist用于声明哪些选择器是安全的、必须留在最终 CSS 中。它有两种形式。简单形式——字符串与正则的数组safelist: [random, yep, button, /^nav-/];复杂形式——对象结构safelist: { standard: [random, yep, button, /^nav-/], deep: [], greedy: [], keyframes: [], variables: [] }例如const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: [random, yep, button], });此时.random、#yep、button三个选择器会留在最终 CSS 中注意字符串会同时匹配 class、id 与标签名三种形态。再如const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: [/red$/], });所有以red结尾的选择器如.bg-red都会被保留。safelist在源码中的标准化逻辑由standardizeSafelist()完成数组形式会被展开为{ standard: [...] }并补齐其他字段的默认值对象形式则与默认结构做浅合并packages/purgecss/src/index.ts。此外isSelectorSafelisted()还会检查一份内部安全名单CSS_SAFELISTpackages/purgecss/src/internal-safelist.ts以及::开头的伪元素这些会被默认保留。safelist.deep连同子选择器一起保留safelist.deep按正则匹配选择器并同时保留其所有后代选择器const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: { deep: [/red$/], }, });此例中即使child-of-bg在内容中从未出现.bg-red .child-of-bg也会被完整保留。实现对应isSelectorSafelistedDeep()packages/purgecss/src/index.ts只要某个选择器片段命中deep正则整条规则立即保留。safelist.greedy任意片段命中即整条保留safelist.greedy更激进只要选择器的任意一部分命中正则整条选择器就保留const purgecss await new PurgeCSS().purge({ content: [], css: [], safelist: { greedy: [/red$/], }, });例如button.bg-red.nonexistent-class即使button与nonexistent-class都未在内容中出现也会被保留。实现对应isSelectorSafelistedGreedy()它会在shouldKeepSelector()里把选择器拆成多个片段逐一比对packages/purgecss/src/index.ts、packages/purgecss/src/index.ts。相关测试覆盖了 children 与 greedy 两种模式见 packages/purgecss/tests/safelist.test.ts。blocklist强制移除选择器blocklist与 safelist 相反即使某个选择器被 extractor 判定为已使用只要命中 blocklist仍会被强制移除blocklist: [usedClass, /^nav-/];即使nav-links和usedClass都被 extractor 提取到它们仍会被删除。对应isSelectorBlocklisted()packages/purgecss/src/index.ts且 blocklist 的优先级高于保留判断——在shouldKeepSelector()中命中 blocklist 的选择器会直接返回false。测试见 packages/purgecss/tests/safelist.test.tsblocklist 用例。skippedContentGlobs跳过不需要扫描的文件当content使用 glob 时可以用skippedContentGlobs排除某些文件或目录skippedContentGlobs: [node_modules/**, components/**];此时 PurgeCSS 不会扫描node_modules与components两个目录。注意当content不是 glob而是具体文件路径时此选项不生效。源码在 glob 展开阶段直接把这些模式透传给glob.sync的ignore参数packages/purgecss/src/index.ts。dynamicAttributes自定义动态属性用于补充aria-selected、data-selected这类自定义动态属性选择器dynamicAttributes: [aria-selected];实现上属性选择器在匹配时会额外检查dynamicAttributes列表以及value、checked、selected、open这四个默认动态属性——因为它们依赖用户交互状态无法从静态内容中可靠推断所以默认总是保留packages/purgecss/src/index.ts。配置文件purgecss.config.js除了直接传选项对象PurgeCSS 也支持读取配置文件。默认配置文件名是purgecss.config.js常量CONFIG_FILENAME见 packages/purgecss/src/constants.ts它是一个普通的 JavaScript 文件module.exports { content: [index.html], css: [style.css], };然后可以在代码中以两种方式使用const purgecss await new PurgeCSS().purge(); // 或把配置文件路径作为唯一参数传入 const purgecss await new PurgeCSS().purge(./purgecss.config.js);setOptions()packages/purgecss/src/index.ts会基于process.cwd()解析并动态import配置文件加载失败时抛出带有 Error loading the config file 前缀的错误错误常量见 packages/purgecss/src/constants.ts。CLI 的--config选项走的也是同一套加载逻辑。命令行界面CLIPurgeCSS 同时提供 CLI既可直接使用也可搭配配置文件使用。先安装全局或作为 devDependency 后配合npx均可npm i -g purgecss运行purgecss --help可查看全部选项Usage: purgecss --css css... --content content... [options] Remove unused css selectors Options: -V, --version output the version number -con, --content files... glob of content files -css, --css files... glob of css files -c, --config path path to the configuration file -o, --output path file path directory to write purged css files to -font, --font-face option to remove unused font-faces -keyframes, --keyframes option to remove unused keyframes -v, --variables option to remove unused variables -rejected, --rejected option to output rejected selectors -rejected-css, --rejected-css option to output rejected css -s, --safelist list... list of classes that should not be removed -b, --blocklist list... list of selectors that should be removed -k, --skippedContentGlobs list... list of glob patterns for folders/files that should not be scanned -h, --help display help for commandCLI 选项与配置文件选项一一对应CLI 入口源码见 packages/purgecss/src/bin.ts基于commander解析参数。--csspurgecss --css css/app.css css/palette.css --content src/index.html--content--content接受多个文件名或 glob 模式文件类型不限HTML、Pug、Blade 等purgecss --css css/app.css --content src/index.html src/**/*.js--config使用配置文件时用-c/--config指定路径purgecss --config ./purgecss.config.js--output默认情况下 CLI 把结果输出到控制台需要落盘时用--output指定输出目录purgecss --css css/app.css --content src/index.html src/**/*.js --output build/css/--safelist防止某个选择器被移除时把它加入 safelistpurgecss --css css/app.css --content src/index.html --safelist classnameToSafelist更完整的 CLI 用法与输出文件测试见 packages/purgecss/tests/cli 下的测试文件包括控制台输出cli-console-output.test.ts、单文件输出cli-file-output.test.ts、多文件输出cli-multiple-files-output.test.ts与选项解析cli-options.test.ts。在 CSS 中直接使用忽略注释Safelisting 进阶除了配置项还可以在 CSS 源码中通过特殊注释直接控制保留行为详见 docs/safelisting.md。使用/* purgecss ignore */保留下一条规则/* purgecss ignore */ h1 { color: blue; }使用/* purgecss ignore current */保留当前规则注释写在规则内部h1 { /* purgecss ignore current */ color: blue; }使用/* purgecss start ignore */与/* purgecss end ignore */保留一段连续范围/* purgecss start ignore */ h1 { color: blue; } h3 { color: green; } /* purgecss end ignore */ h4 { color: purple; }这些注释对应的常量与识别逻辑分别在 packages/purgecss/src/constants.ts 与isIgnoreAnnotation()、hasIgnoreAnnotation()packages/purgecss/src/index.ts中purgecss ignore下一条、purgecss ignore current当前规则内部、purgecss start ignore/purgecss end ignore范围开关。注释本身在处理完成后会被从输出中移除。一个重要的坑GotchasPostCSS、cssnano 等 CSS 优化工具在构建流程中可能先于 PurgeCSS 剥离注释导致忽略注释失效。由于这些步骤在开发模式下常常被跳过问题容易被忽视。解决办法是用感叹号把注释标记为重要注释/*! purgecss start ignore */ h5 { color: pink; } h6 { color: lightcoral; } /*! purgecss end ignore */这样压缩工具会保留它们PurgeCSS 仍能识别。Extractors提取器的机制与扩展PurgeCSS 依赖 extractor 从内容文件中获取使用了哪些选择器。HTML、Pug、JS 等不同类型的文件都可能包含选择器因此提取器需要按文件类型适配详见 docs/extractors.md。默认 extractor适用于所有文件类型但能力有限它把文件中的每个词都视为选择器不识别、:、/等特殊字符在复杂模板场景下可能提取不充分。自定义 extractor就是一个普通函数接收文件内容字符串返回选择器数组tags、classes、ids或返回结构更精细的对象interface ExtractorResultDetailed { attributes: { names: string[]; values: string[]; }; classes: string[]; ids: string[]; tags: string[]; undetermined: string[]; }const purgeFromJs (content) { // 返回 css selector 数组 };返回详细对象能让 PurgeCSS 获得更好的匹配精度在ExtractorResultSetspackages/purgecss/src/ExtractorResultSets.ts中这些结果被拆分到attrNames、attrValues、classes、ids、tags、undetermined六个集合里分别支撑属性名、属性值、类、ID、标签的精确匹配无法归类的词进入undetermined在各类匹配时兜底参与判断例如hasClass()会同时检查classes与undetermined。在配置中使用 extractor 的完整示例import { purgeCSSFromPug } from purgecss-from-pug; import { purgeCSSFromHtml } from purgecss-from-html; const options { content: [], // 用于提取选择器的文件 css: [], // css extractors: [ { extractor: purgeCSSFromPug, extensions: [pug], }, { extractor: purgeCSSFromHtml, extensions: [html], }, ], }; export default options;约定俗成的命名规则是purgecss-from-[文件类型]如purgecss-from-pug便于在 npm 上搜索同类提取器。仓库中已经实现并发布了多个提取器包purgecss-from-htmlpackages/purgecss-from-html、purgecss-from-jsxpackages/purgecss-from-jsx、purgecss-from-tsxpackages/purgecss-from-tsx、purgecss-from-pugpackages/purgecss-from-pug。官方文档提示这些提取器仍处于演进阶段生产环境使用前需自行评估。生态monorepo 中的包与插件当前仓库是一个用 Lerna 管理的 monorepo见根目录 lerna.json多个包从同一份代码库发布到 npm。README 列出的核心包如下各包详情可从 packages 目录进入Package说明purgecssPurgeCSS 的核心包包含分析文件、移除未使用 CSS 的核心方法postcss-purgecss面向 PostCSS 的 PurgeCSS 插件purgecss-webpack-plugin面向 Webpack 的 PurgeCSS 插件gulp-purgecss面向 Gulp 的 PurgeCSS 插件grunt-purgecss面向 Grunt 的 PurgeCSS 插件rollup-plugin-purgecss面向 Rollup 的 PurgeCSS 插件purgecss-from-htmlHTML 提取器purgecss-from-pugPug 提取器purgecss-with-wordpress面向 WordPress 的 safelist 集合vue-cli-plugin-purgecssVue CLI 插件绝大多数构建工具与框架都在使用 PostCSS因此最快上手 PurgeCSS 的方式是使用其 PostCSS 插件docs/plugins/postcss.mdnpm i -D fullhuman/postcss-purgecssconst purgecss require(fullhuman/postcss-purgecss); module.exports { plugins: [ purgecss({ content: [./**/*.html], }), ], };仓库还提供了面向各主流框架的接入指南可作为对应生态下的实战参考前端框架Vue.js、Nuxt.js、React.js、Next.js、Razzle静态站点与 CMSHugo、WordPress构建工具插件Webpack、Gulp、Grunt、Gatsby进一步阅读配置选项全解全部选项、类型定义与可复制示例命令行界面CLI 安装、参数与输出编程式 APIES Module / CommonJS 两种用法与返回结构Safelistingsafelist 各种形态与 CSS 内注释的完整说明Extractors默认提取器局限、自定义提取器与结果结构Comparison与其他同类工具/方案的对比核心实现packages/purgecss/src/index.ts 中的PurgeCSS类、shouldKeepSelector()、walkThroughCSS()以及 packages/purgecss/src/ExtractorResultSets.ts 中的选择器结果集赞分享前端构建工具【免费下载链接】purgecssRemove unused CSS项目地址https://gitcode.com/gh_mirrors/pu/purgecss点击查看免费下载相关推荐PurgeCSS 入门指南高效移除未使用的CSS样式PurgeCSS 入门指南高效移除未使用的CSS样式 什么是PurgeCSS PurgeCSS 是一款专门用于移除项目中未使用CSS的工具。在现代前端开发中前端构建工具PurgeCSS深度解析如何高效移除未使用的CSS样式PurgeCSS深度解析如何高效移除未使用的CSS样式 什么是PurgeCSS PurgeCSS是一款专门用于移除项目中未使用CSS代码的工具。在现代前端开发前端构建工具PurgeCSS 快速上手用 PostCSS 插件移除未使用 CSS 的完整指南PurgeCSS 快速上手用 PostCSS 插件移除未使用 CSS 的完整指南 本篇指南讲解在当前 PurgeCSS 仓库中推荐的快速入门路径通过 fu前端构建工具上一篇DeepSeek-Math 完整使用指南10个快速上手技巧 下一篇如何让老旧Mac焕发新生OpenCore Legacy Patcher完全解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
