如何使用Rollup打包支持CSS Module与SCSS的TS React组件库并解决样式失效问题

你的推测是正确的，CSS Module生成的类名在JS逻辑与输出样式中不匹配是该问题的核心诱因。

核心问题触发逻辑 #

CSS Module的核心原理是在编译阶段给类名添加唯一哈希后缀，避免样式冲突。如果Rollup打包过程中，JS文件内的类名替换规则、CSS文件内的类名生成规则不一致，就会导致最终渲染的DOM类名和样式表中的类名无法对应，样式自然不生效。

常见配置错误与修复方案 #

• 未显式指定类名生成规则
  默认的postcss CSS Module配置没有固定类名生成逻辑，不同环境/版本下可能出现哈希生成结果不一致的问题，需要显式配置generateScopedName统一规则，同时可以添加固定前缀避免和用户项目的类名哈希冲突：

postcss({
  modules: {
    // 统一类名生成规则，保证JS和CSS中的类名完全匹配
    generateScopedName: '[name]__[local]___[hash:base64:5]',
    // 可选：仅识别后缀为.module.scss/.module.css的文件为CSS Module，避免全局样式被误编译
    auto: /\.module\.(scss|sass|css)$/,
    // 可选：添加组件库专属前缀，进一步降低哈希冲突概率
    hashPrefix: 'your-component-lib-prefix'
  },
  use: ['sass'],
  // 可选：如果需要抽离独立CSS文件，配置输出路径，否则样式会默认注入到JS中运行时插入页面
  extract: 'dist/index.css'
})

• 抽离CSS后未提示用户引入
  如果你配置了extract参数单独抽离CSS文件，需要在组件库的使用文档中明确提示用户在项目入口引入全局样式：import 'your-lib-name/dist/index.css'
• CSS Module识别范围错误
  如果全局开启modules: true，会将所有scss/css文件都按照CSS Module处理，如果你组件库中有全局重置样式、公共样式，会被错误编译类名导致失效，建议开启auto参数仅识别带.module后缀的样式文件为CSS Module。

验证方法 #

打包完成后打开dist目录下的产物：

1. 找到组件对应的JS产物，查找你代码中用到的类名（比如container）编译后的最终字符串
2. 打开输出的CSS文件，查找对应的类名，两者完全一致才属于配置正确

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