使用 PurgeCSS 清除 Nuxt.js 未使用 CSS：nuxt-purgecss 模块与 PostCSS 插件双方案实战指南-迪斯科星球

前端
构建工具

【免费下载链接】purgecss

Remove unused CSS

项目地址：https://gitcode.com/gh_mirrors/pu/purgecss

本文聚焦 PurgeCSS 在 Nuxt.js 项目中的两种接入方式：社区模块nuxt-purgecss（开箱即用的默认配置）与@fullhuman/postcss-purgecss（PostCSS 插件，可细粒度控制），并深入当前仓库源码解析底层实现。读完你可以掌握两种方案的安装注册、完整参数含义、配置合并机制，以及如何结合 Nuxt 的buildModules/build.postcss配置在生产构建中自动剔除未使用样式。

为什么要在 Nuxt.js 中使用 PurgeCSS

Nuxt.js 预置了开发 Vue.js 应用所需的全部配置，能够产出 Universal（同构渲染）、SPA（单页应用）与 Static Generated（静态站点）三类应用。这类应用普遍通过组件、布局与页面组织样式，随着项目迭代，CSS 中很容易积累大量从未被模板实际引用的规则——尤其是引入 Bootstrap、Tailwind 这类重量级框架或 UI 库时，未使用样式可能占据最终产物的很大比例。

PurgeCSS 的核心工作就是"移除未使用的 CSS"（Remove unused CSS）：它扫描内容文件（HTML、Vue、JS 等）中实际出现的类名、ID、标签与属性，然后删掉样式表中对应的选择器。在 Nuxt 项目中，接入方式主要有两条路径，对应本文的两大章节：

nuxt-purgecss社区模块：把 PurgeCSS 包装成 Nuxt 模块，提供针对 Vue 项目设计的默认配置，改动量最小；
@fullhuman/postcss-purgecssPostCSS 插件：直接挂到 Nuxt 的 PostCSS 处理链上，配置项完全继承 PurgeCSS 核心能力，灵活度更高。

仓库中的对应实现位于 packages/postcss-purgecss，核心包为 packages/purgecss，本文后续的源码分析均以此为准。

方案一：使用 nuxt-purgecss 社区模块

nuxt-purgecss是一个社区模块，目标是把 PurgeCSS 与 Nuxt 的集成做到"尽可能简单"：它内置了贴合 Vue/Nuxt 项目结构的默认配置，大多数项目几乎不需要额外修改即可获得合理的清理效果。

安装与注册

安装分两步：

使用 yarn 或 npm 为项目添加nuxt-purgecss依赖；
在nuxt.config.js的模块区注册它。

官方给出的注册方式如下：

{ buildModules: [ // 如果使用 nuxt < 2.9.0，请改用 modules 属性 'nuxt-purgecss', ], purgeCSS: { // your settings here } }

要点说明：

buildModules与modules：buildModules仅在构建阶段生效，适合 PurgeCSS 这类"构建时工具"；若你的 Nuxt 版本低于 2.9.0，则必须使用modules属性。两者选其一即可，不要同时注册。
purgeCSS配置节点：模块会读取顶层purgeCSS键作为配置，下方// your settings here处填写的是 PurgeCSS 相关选项。

模块默认配置解析

在深入逐项参数之前，先看模块自带的完整默认配置：

{ mode: MODES.webpack, enabled: ({ isDev, isClient }) => (!isDev && isClient), // 或 false（处于 dev/debug 模式时） paths: [ 'components/**/*.vue', 'layouts/**/*.vue', 'pages/**/*.vue', 'plugins/**/*.js' ], styleExtensions: ['.css'], whitelist: ['body', 'html', 'nuxt-progress'], extractors: [ { extractor: content => content.match(/[A-z0-9-:\\/]+/g) || [], extensions: ['html', 'vue', 'js'] } ] }

这套默认值的用意非常贴合 Nuxt 项目结构：

配置项	默认值	含义
`mode`	`webpack`	PurgeCSS 以 webpack 模式还是 postcss 模式工作
`enabled`	`({ isDev, isClient }) => (!isDev && isClient)`	仅在生产环境的客户端构建中启用
`paths`	四个 glob	默认扫描`components`、`layouts`、`pages`下的`.vue`文件与`plugins`下的`.js`文件
`styleExtensions`	`['.css']`	只处理`.css`扩展名的样式文件
`whitelist`	`['body', 'html', 'nuxt-progress']`	保留全局必需的三个选择器
`extractors`	一个默认提取器	从`html`/`vue`/`js`内容中提取选择器

命名提示：whitelist是 PurgeCSS 2.x 时期的叫法，在 PurgeCSS 3.0 及以后（docs/safelisting.md 即面向 3.0+）已更名为safelist，本仓库 defaultOptions 中的 safelist 即为标准形态。集成时请留意模块文档对应的版本口径。

这套默认配置可以作为各类项目起步的坚实基础。

配置合并机制：函数优先，静态值合并

nuxt-purgecss的每个配置项都支持两种写法：函数或静态值（基本类型、对象、数组等）。

若写成函数，函数会收到"默认值"作为第一个参数，由你自行决定如何使用它；
若写成静态值，模块会尝试把它与默认值合并。

合并行为对paths、whitelist这类"默认值本身就很合理"的选项非常友好——你只需要补充自己新增的目录或选择器，而不会丢掉默认项。如果希望完全丢弃默认值、只用自己定义的内容，就改用函数写法。

配置项深入剖析

mode

类型：String（webpack或postcss）
默认值：webpack

决定 PurgeCSS 以何种方式接入构建。两种模式各有硬性前提：

webpack 模式：只能在build.extractCSS: true时使用（即启用 Nuxt 的 CSS 提取，PurgeCSS 在 webpack 编译阶段处理提取出的 CSS）；
postcss 模式：只能在build.postcss为对象（不能是数组）或使用默认设置时使用（PurgeCSS 以 PostCSS 插件身份参与样式处理链）。

enabled

类型：Boolean或Function（函数仅用于 webpack 模式，会收到 build 的 extend context）
默认值：({ isDev, isClient }) => (!isDev && isClient)（仅生产模式激活），debug/dev 模式下为false

控制模块整体开关：

求值为false时，模块完全不会被激活；
传入函数时，在 webpack 模式下会被正确求值；在 postcss 模式下则一律按true处理（此时通常应使用静态布尔值控制）。

默认值的设计很巧妙：!isDev && isClient意味着只在生产构建且为客户端一侧时执行清理，开发模式保留全部样式以加速热更新与调试。

paths：以 paths 取代 content

其他 PurgeCSS 相关选项请参考仓库内的 docs/configuration.md。一个关键区别是：在 Nuxt 模块语境下，不用content，而是用paths指定 PurgeCSS 应扫描的文件路径。这一点对webpack与postcss两种模式都成立，并不仅限于 webpack 模式。

paths的写法与 PurgeCSS 的content一致，支持 glob 通配，例如默认值中的'components/**/*.vue'会递归匹配components目录下所有.vue单文件组件。

extractors 与默认提取器

默认提取器用正则/[A-z0-9-:\\/]+/g从内容中抓取候选选择器，并声明其适用于html、vue、js三种扩展名。vue单文件组件（模板 + 脚本 + 样式三段式结构）正适合这种"整文件扫一遍"的提取方式。

更精确的提取器方案可参考 docs/extractors.md：当发现默认提取器漏删或误删时，可改用按扩展名定制的提取器（仓库同时提供了purgecss-from-html、purgecss-from-jsx、purgecss-from-pug、purgecss-from-tsx等独立包，见 packages 目录），或者自定义 extractor 函数，返回类名、ID、标签、属性名/值等结构化结果以获得更高精度。

方案二：使用 PostCSS 插件（@fullhuman/postcss-purgecss）

前置说明：extractCSS 与 CSS 文件

Nuxt 的extractCSS选项会让 CSS 被提取为独立文件、由浏览器单独加载。应用规模变大后，这些文件可能数量众多且碎片化；若希望把 CSS 内联进 HTML 的<head>中，就需要在 PostCSS 层面完成样式处理。使用本方案时请留意：该配置下 PurgeCSS 会在生产与开发两种模式中都保持激活（与方案一的默认"仅生产启用"不同，需要自行权衡）。

安装

根据包管理器二选一：

# NPM npm i -D @fullhuman/postcss-purgecss

# YARN yarn add @fullhuman/postcss-purgecss --dev

该包对应仓库内的 packages/postcss-purgecss，其 README 明确说明：PurgeCSS 的全部选项均可通过该插件使用。

在 nuxt.config.js 中接入

在build.postcss的插件列表中注册（build.postcss必须是对象形式）：

'@fullhuman/postcss-purgecss': { content: ['./pages/**/*.vue', './layouts/**/*.vue', './components/**/*.vue'], safelist: ['html', 'body'] }

content：声明需要被扫描的内容文件 glob，这里覆盖了 Nuxt 中最可能引用样式的三个目录；该选项为必填（除非改用contentFunction）。
safelist：['html', 'body']保证文档根元素与 body 相关的基础样式（如 reset、默认字体）不会被误删。

插件的常用选项详解

插件完全继承 PurgeCSS 核心包的选项能力，以下是在 Nuxt 场景中最常使用的几个（完整清单见 packages/postcss-purgecss/README.md 与 docs/configuration.md）：

content（必填）/ contentFunctioncontent接收文件名或 glob 数组，文件可以是 HTML、Vue、Pug 等任意含选择器的内容。需要"按输入文件动态决定扫描范围"时，改用contentFunction：它接收当前源文件路径并返回内容 glob 数组，例如按组件文件自动定位同名模板。插件源码会在 index.ts 中调用该函数并把返回结果写入options.content。

safelist / blocklist

safelist：保留最终 CSS 中的选择器，支持简单数组（字符串或正则，如['random', 'yep', 'button', /^nav-/]）与复杂对象（standard、deep、greedy、keyframes、variables五个子项），详见 docs/safelisting.md。Nuxt 项目里常见的做法是把html、body、#__nuxt、.nuxt-progress这类框架运行时必需的挂载点/进度条选择器放入 safelist。
blocklist：与 safelist 相反，即使某选择器被提取器判定为已使用，也会被强制移除。

skippedContentGlobs当content使用 glob 时，可额外传入排除 glob，跳过node_modules/**、components/**等无需扫描的目录（对非 glob 的 content 无效）。

rejected（默认 false）设为true后，被清除的选择器会以 PostCSS message 形式输出，配合postcss-reporter之类插件可在终端打印被移除的选择器，便于排查误删。源码实现见 packages/postcss-purgecss/src/index.ts#L95-L105。

keyframes / fontFace / variables（均默认 false）

keyframes: true可移除未使用的@keyframes动画（适合 animate.css 这类动画库）；
fontFace: true可移除未被引用的@font-face规则；
variables: true可清理未使用的 CSS 自定义属性。

这些清理步骤在插件源码中以 removeUnusedKeyframes / removeUnusedFontFaces / removeUnusedCSSVariables 顺序执行，均有对应测试用例验证（见 packages/postcss-purgecss/tests/index.test.ts 与 font-keyframes 测试夹具）。

从源码看 PostCSS 插件的工作流程

结合 packages/postcss-purgecss/src/index.ts，可以梳理出插件一次构建中的完整调用链：

注册钩子：插件以OnceExit钩子挂入 PostCSS（第 123 行），即在样式处理链的"出口"统一执行清理，因此它能感知链上前置插件对选择器的改写（测试中用一个为类选择器加前缀的 mock 插件验证了这一点）。
合并配置：插件按"内置默认值 →purgecss.config.js配置文件 → 插件入参opts"的优先级合并选项，并在启动时自动探测当前工作目录下的purgecss.config.js（第 39-54 行）。内置默认值定义在核心包的 options.ts，其中fontFace、keyframes、rejected、variables等均默认为false。
提取选择器：将content中的字符串路径与原始内容（raw）对象分流，分别调用extractSelectorsFromFiles与extractSelectorsFromString，最后合并为选择器集合。
遍历清理：walkThroughCSS(root, selectors)逐条比对 CSS 节点并删除未使用选择器，随后按需执行fontFace/keyframes/variables清理。
输出报告：开启rejected时，把selectorsRemoved中累积的被删选择器打包成一条 PostCSS message 推入result.messages。

这套流程也印证了 PostCSS 插件在 Nuxt 中的定位：它是"样式管道的最后一环"，确保最终输出到 HTML 或独立 CSS 文件中的样式都是被实际使用的。

两种方案如何选择

维度	nuxt-purgecss 模块	@fullhuman/postcss-purgecss 插件
接入方式	Nuxt`buildModules`（旧版`modules`）	Nuxt`build.postcss`插件列表
配置入口	顶层`purgeCSS`节点	插件对象字面量
默认行为	仅生产 + 客户端构建启用，默认扫描 Vue/JS 目录	生产与开发模式均激活
依赖模式	`webpack`模式需`build.extractCSS: true`；`postcss`模式需`build.postcss`为对象	直接作为 PostCSS 插件存在
配置自由度	基于模块默认值做函数/静态值合并	完整继承 PurgeCSS 全部选项，自由度最高
适用场景	想以最小配置获得合理清理效果	需要对 content、safelist、keyframes、fontFace 等做精细化控制

小结

在 Nuxt.js 项目中接入 PurgeCSS 有两条成熟路径：nuxt-purgecss模块以贴合 Vue 项目结构的默认值（paths覆盖 components/layouts/pages/plugins、仅生产客户端启用、内置 body/html 白名单）让集成成本趋近于零；@fullhuman/postcss-purgecss插件则把 PurgeCSS 的全部配置能力搬进build.postcss，适合需要精确控制扫描范围、安全名单与 keyframes/fontFace/variables 清理行为的场景。无论选择哪条路径，核心包 packages/purgecss 与插件包 packages/postcss-purgecss 的源码、配置文档、安全名单文档与提取器文档都是排查问题、深挖行为时的权威参考。

前端
构建工具

【免费下载链接】purgecss

Remove unused CSS

项目地址：https://gitcode.com/gh_mirrors/pu/purgecss

点击查看免费下载

企业官网建设流程全解析

【免费下载链接】purgecss

为什么要在 Nuxt.js 中使用 PurgeCSS

方案一：使用 nuxt-purgecss 社区模块

安装与注册

模块默认配置解析

配置合并机制：函数优先，静态值合并

配置项深入剖析

mode

enabled

paths：以 paths 取代 content

extractors 与默认提取器

方案二：使用 PostCSS 插件（@fullhuman/postcss-purgecss）

前置说明：extractCSS 与 CSS 文件

安装

在 nuxt.config.js 中接入

插件的常用选项详解

从源码看 PostCSS 插件的工作流程

两种方案如何选择

小结

【免费下载链接】purgecss

相关推荐

grunt-purgecss 实战指南：在 Grunt 构建流程中集成 PurgeCSS 清除无用 CSS

PentestGPT 执行 make docker-run 直接退出码 2 并提示 pentestgpt_agent 未打进镜像怎么排查？

使用 PurgeCSS 优化 WordPress 主题：purgecss-with-wordpress 安全名单（Safelist）实战指南

热门文章

文章分类

标签云

需要专业的网站建设服务？

企业官网建设流程全解析

【免费下载链接】purgecss

为什么要在 Nuxt.js 中使用 PurgeCSS

方案一：使用 nuxt-purgecss 社区模块

安装与注册

模块默认配置解析

配置合并机制：函数优先，静态值合并

配置项深入剖析

mode

enabled

paths：以 paths 取代 content

extractors 与默认提取器

方案二：使用 PostCSS 插件（@fullhuman/postcss-purgecss）

前置说明：extractCSS 与 CSS 文件

安装

在 nuxt.config.js 中接入

插件的常用选项详解

从源码看 PostCSS 插件的工作流程

两种方案如何选择

小结

【免费下载链接】purgecss

相关推荐

grunt-purgecss 实战指南：在 Grunt 构建流程中集成 PurgeCSS 清除无用 CSS

PentestGPT 执行 make docker-run 直接退出码 2 并提示 pentestgpt_agent 未打进镜像怎么排查？

使用 PurgeCSS 优化 WordPress 主题：purgecss-with-wordpress 安全名单（Safelist）实战指南

热门文章

文章分类

标签云

相关文章

AI写论文如何避开查重与AI检测？合规辅助全流程拆解

阿里 Qwen3-Max-Thinking 接入 TaoToken：统一 Key 打通国产大模型调用链路

【Agent】【OpenCode】项目配置（命名空间）实战：用 TaoToken 统一 Key 打通多 Agent 工作区

需要专业的网站建设服务？