如何在Vite 4.x项目中结合PurgeCSS、React与CSS Modules使用？

问题根源 #

1. 直接使用@fullhuman/postcss-purgecss处理CSS Modules时，PurgeCSS无法识别经过哈希处理的模块化类名（如Button_container__abc123）与React组件中对应的类名映射，导致误删所有样式代码。
2. Vite默认不会在打包阶段移除CSS Modules中未使用类名的JS导出，使得后执行的PurgeCSS扫描JS文件时会读取到所有类名，无法完成有效清理。

可行解决方案 #

方案1：使用vite-plugin-purgecss（推荐） #

该插件专为Vite构建流程适配，能精准识别CSS Modules和React的类名引用：

1. 安装依赖

npm install vite-plugin-purgecss --save-dev
# 或
yarn add vite-plugin-purgecss -D

2. 在vite.config.js中配置插件：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import purgecss from 'vite-plugin-purgecss'

export default defineConfig({
  plugins: [
    react(),
    purgecss({
      content: ['./index.html', './src/**/*.jsx', './src/**/*.js'],
      // 适配Vite默认的CSS Modules哈希类名格式，避免误删有效样式
      safelist: {
        standard: [/^[a-z]+-[a-z]+__[a-z0-9]+$/],
      },
      // 仅在生产构建时启用
      enabled: process.env.NODE_ENV === 'production'
    })
  ],
  // 确认CSS Modules配置（Vite默认已支持，可按需调整）
  css: {
    modules: {
      generateScopedName: '[name]__[local]___[hash:base64:5]'
    }
  }
})

此方案无需额外postbuild命令，插件会在Vite构建过程中直接处理CSS，精准保留实际使用的类名。

方案2：优化postbuild命令（适合坚持用CLI工具的场景） #

先让Vite移除未使用的CSS Modules类名导出，再执行PurgeCSS：

1. 安装rollup-plugin-purgecss

npm install rollup-plugin-purgecss --save-dev

2. 修改vite.config.js添加Rollup插件：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import purgecss from 'rollup-plugin-purgecss'

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      plugins: [
        purgecss({
          content: ['./src/**/*.jsx', './src/**/*.js'],
          css: ['./src/**/*.module.css']
        })
      ]
    }
  }
})

3. 调整postbuild命令：

{
  "scripts": {
    "build": "vite build",
    "postbuild": "purgecss --css build/static/css/*.css --content build/index.html build/static/js/*.js --output build/static/css --safelist \"^[a-z]+-[a-z]+__[a-z0-9]+$\""
  }
}

这里的safelist用来匹配CSS Modules的哈希类名格式，确保有效样式不被误删。

关键注意事项 #

• 所有CSS Modules文件必须以.module.css为后缀，Vite才会将其识别为模块化样式。
• 全局CSS与CSS Modules语法要分开使用，避免混淆处理逻辑。
• 构建完成后需验证：打包后的CSS仅保留实际用到的类名，同时页面样式显示正常。

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