如何将React组件的JSX与CSS Modules编译为可静态导入的.css文件？

背景 #

我正在开发一个包含React UI组件的公开Node包，目前使用CSS Modules为组件做样式隔离，通过Webpack可成功打包并输出main.css文件。

需求 #

由于计划在不同框架的多个项目中使用该组件，无法保证这些项目都支持CSS Modules。因此我希望在构建阶段就将CSS Modules生成的类名直接固化到编译后的JSX中，而非依赖是否导入CSS Modules来动态添加，之后只需导入编译后的.css文件即可使用。

已调研内容 #

• 一款专门针对CSS Modules的工具似乎能解决该问题，但该工具已不再维护，想知道是否有更优方案。
• 想了解是否可通过PostCSS流程或现有PostCSS插件实现该需求。

方案1：使用babel-plugin-react-css-modules（推荐） #

这个插件能在Babel编译阶段直接将CSS Modules的动态类名替换为固化的哈希类名，完全脱离运行时对CSS Modules的依赖。

配置要点 #

1. 确保Webpack配置中，css-loader的modules选项开启，且generateScopedName规则和Babel插件保持一致（比如都设为[name]__[local]___[hash:base64:5]），保证JSX中的类名和输出CSS里的类名完全匹配。
2. 在Babel配置文件（如babel.config.js）中添加插件配置：

module.exports = {
  plugins: [
    [
      'react-css-modules',
      {
        generateScopedName: '[name]__[local]___[hash:base64:5]',
        filetypes: {
          '.css': { syntax: 'postcss' }
        },
        handleMissingStyleName: 'throw' // 可选，用于检测未定义的类名
      }
    ]
  ]
};

3. 组件中使用styleName替代className来绑定样式类，插件会自动将其替换为固化的类名：

// 原代码
import styles from './Button.css';
const Button = () => <button styleName="primary">Click Me</button>;

// 编译后输出
const Button = () => <button className="Button__primary___abc12">Click Me</button>;

4. Webpack打包时依然正常输出main.css，最终用户只需引入这个CSS文件和编译后的组件即可使用，无需任何CSS Modules支持。

方案2：自定义Webpack + PostCSS组合方案 #

如果不想引入额外Babel插件，可以通过PostCSS配合Webpack的自定义插件实现：

1. 使用postcss-modules插件提取所有CSS Modules的类名映射，生成一个JSON文件记录原类名 -> 哈希类名的对应关系。
2. 编写一个简单的Webpack插件，在编译JSX时读取这个JSON文件，将所有动态的styles.xxx替换为对应的哈希类名字符串。
3. 这种方式需要自己处理类名替换的逻辑，灵活性高但工作量稍大，适合对构建流程有定制需求的场景。

方案3：切换到静态CSS类名策略 #

如果上述插件方案不符合需求，也可以放弃自动哈希类名，手动给组件样式使用唯一前缀（如my-ui-button-primary），直接在JSX中写死类名，同时打包输出带前缀的CSS文件。这种方式最简单，但需要手动维护类名唯一性，适合组件数量较少的场景。

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