Angular中使用PurgeCSS移除未使用CSS的问题排查

问题概述 #

在 Angular 16.2.2 中使用 PurgeCSS v5.0.0（webpack 插件）移除未使用 CSS 时遇到以下问题：

• 压缩后的 CSS 仍包含未使用的注入变量和多余类，文件体积达 30KB，超出预期
• 调整路径配置后体积降至 6KB，但部署后样式错乱
• 改用 postbuild 方式执行 PurgeCSS，体积仍为 30KB，且 variables 参数无效，所有变量均保留

当前配置如下：

webpack.config.js #

const glob = require('glob');
const { PurgeCSSPlugin } = require('purgecss-webpack-plugin');

module.exports = {
  plugins: [
    new PurgeCSSPlugin({ 
      paths: glob.sync('./src/**/*', { nodir: true }),
      safelist: {
        standard: [/^leaflet-/]
      }
    })
  ]
};

angular.json（build 片段） #

"build": {
  "builder": "@angular-builders/custom-webpack:browser",
  "options": {
    "outputPath": "dist/browser",
    "index": "src/index.html",
    "main": "src/main.ts",
    "polyfills": ["zone.js"],
    "tsConfig": "tsconfig.app.json",
    "inlineStyleLanguage": "scss",
    "assets": [
      "src/favicon.ico",
      "src/assets",
      "src/robots.txt",
      "src/ads.txt",
      {
        "glob": "**/*",
        "input": "node_modules/leaflet/dist/images/",
        "output": "./assets"
      }
    ],
    "styles": [
      "src/styles.scss",
      "src/styles-fonts.scss"
    ],
    "scripts": [],
    "customWebpackConfig": {
      "path": "webpack.config.js"
    }
  },

解决方案 #

一、修正 PurgeCSS 路径匹配与安全列表配置 #

路径未覆盖所有模板文件、安全列表不全是核心问题，调整 webpack.config.js：

const glob = require('glob');
const { PurgeCSSPlugin } = require('purgecss-webpack-plugin');

const PATHS = {
  src: './src'
};

module.exports = {
  plugins: [
    new PurgeCSSPlugin({
      // 覆盖所有组件模板、逻辑文件、样式文件
      paths: glob.sync(`${PATHS.src}/**/*.{html,ts,scss}`, { nodir: true }),
      safelist: {
        // 保留 Leaflet 样式
        standard: [/^leaflet-/, /^ng-/],
        // 保留 Bootstrap 动态类（响应式、状态类等）
        greedy: [/^col-/, /^btn-/, /^alert-/, /^form-/]
      },
      // 移除未使用的 CSS 变量
      variables: true,
      // 移除未使用的关键帧动画
      keyframes: true
    })
  ]
};

• 扩展路径匹配范围，确保捕获所有可能引用样式的文件
• 补充安全列表，避免 Angular 内置类、Bootstrap 动态类被误删
• 启用 variables 和 keyframes 参数清理冗余代码

二、调整 Angular 构建优化配置 #

在 angular.json 的 build.options 中添加协同配置：

"build": {
  "builder": "@angular-builders/custom-webpack:browser",
  "options": {
    // ... 原有配置
    "optimization": {
      "styles": {
        "minify": true,
        "inlineCritical": false
      }
    },
    "customWebpackConfig": {
      "path": "webpack.config.js",
      "mergeStrategies": {
        "plugins": "append"
      }
    }
  },

• 启用 CSS 压缩，确保最终输出的文件体积最小化
• 关闭 critical CSS 内联，避免干扰 PurgeCSS 的处理逻辑
• 配置插件合并策略，确保 PurgeCSS 被正确注入构建流程

三、postbuild 方式的正确配置 #

若偏好 postbuild 处理，直接针对构建后的产物操作：

1. 在 package.json 中添加脚本：

"scripts": {
  // ... 原有脚本
  "postbuild": "purgecss --css dist/browser/*.css --content dist/browser/index.html dist/browser/main*.js --safelist 'leaflet-*,ng-*,col-*,btn-*' --variables --keyframes --output dist/browser/"
}

2. 关键说明：

• 直接处理构建后的 CSS 文件
• 内容源包含编译后的 HTML 和 JS 文件（Angular 组件模板会打包进 JS）
• 明确指定安全列表和清理参数，确保冗余代码被移除

四、验证与调试 #

• 构建后检查 dist/browser 下的 CSS 文件，确认冗余内容是否被清理
• 使用 --print-rejected 参数查看被移除的样式，排查误删问题：

purgecss --css dist/browser/*.css --content dist/browser/index.html dist/browser/main*.js --safelist 'leaflet-*,ng-*,col-*,btn-*' --variables --keyframes --print-rejected

• 根据输出补充安全列表，确保必要样式被保留

内容的提问来源于stack exchange，提问作者Carlos Torrecillas