CSS Modules中需用:global()声明全局类，推荐将Bootstrap等工具类统一放入globals.css；动态拼接样式应使用clsx或预定义styles.xxx；composes比@extend更安全可靠；SSR需确保客户端与服务端css-loader配置一致以避免哈希不一致。
如何在CSS Modules中正确引入全局类
CSS Modules默认把所有类名都局部化，想用btn这种通用组件类或text-center这类工具类？不能直接写className="btn text-center"——它会被编译成带哈希的局部名，全局样式就失效了。
必须显式声明哪些类不走模块化。常见错误是漏加:global，或者只包了一部分：
-
:global(.btn) { ... }✅ 正确：整个.btn规则脱离模块作用域 -
.container :global(.btn) { ... }✅ 正确：仅.btn部分全局，父选择器仍局部化 -
:global(.btn .text-center)❌ 危险：如果.text-center本身是另一个CSS文件里的全局类，这里重复声明可能覆盖原意
实际项目里，建议把第三方UI库（如Bootstrap）或自定义工具类统一放在一个globals.css里，再用@import引入，避免零散:global()污染每个模块文件。
动态拼接样式名时怎么保留局部作用域
React里常用className={`${styles.container} ${isDark ? styles.dark : styles.light}`}，这没问题；但一旦混入字符串拼接、变量插值或第三方类名，就容易破环局部性。
立即学习“前端免费学习笔记（深入）”；
典型翻车现场：
-
className={`${styles.container} ${theme}-mode`}→theme是字符串变量，-mode不会被CSS Modules处理，结果就是dark-mode类名裸奔，没哈希，也没局部作用域保护 -
className={styles.container + ' ' + getCustomClass()}→ 如果getCustomClass()返回"active highlight"，这两个类全变成全局引用
安全做法只有两个：
- 所有可能变化的类名，提前定义在
module.css里，比如.dark-mode、.light-mode，然后通过styles['dark-mode']取值 - 用
clsx或classnames这类库，它们只做字符串拼接，不干预CSS Modules逻辑，但前提是你传进去的每个值都是合法的styles.xxx或明确的:global()类
为什么composes比@extend更可靠
CSS Modules的composes不是简单的样式继承，而是编译期的类名组合：它把目标类的哈希后名称也拼进当前类的className，保证运行时两个局部类同时生效。
比如：.button { composes: theme from './base.module.css'; }，最终生成的button类会同时包含自己和theme的哈希名，且顺序可控。
对比Sass的@extend：
-
@extend是CSS层合并选择器，可能导致意外的权重提升或选择器爆炸 -
composes不改变CSS结构，只影响JS层传给className的字符串，对打包体积、浏览器渲染无额外负担 - 注意：
composes只能跨文件复用同为CSS Modules的类，不能composes: btn from 'bootstrap.css'——后者不是模块，得走:global(.btn)
服务端渲染（SSR）下CSS Modules类名不一致的坑
开发时一切正常，部署到Node.js服务端渲染环境后，发现按钮样式错乱——大概率是CSS Modules在客户端和服务端生成了不同哈希。
根本原因是：默认情况下，CSS Modules的哈希基于文件路径+内容生成，但Webpack在SSR构建时可能用了不同output.path或resolve.alias，导致路径字符串不一致。
解决方式很具体：
- 确保客户端和服务端使用同一份
css-loader配置，尤其modules.exportLocalsConvention和modules.getLocalIdent必须完全一致 - 禁用
css-loader的modules.auto，显式设为true，防止某些文件被误判为非模块 - 更稳妥的做法：用
webpack-plugin-css-modules-typescript之类插件，在构建时导出类型定义，强制类名字符串在TS层面可校验，提前暴露拼写错误
这个点特别容易被忽略——因为本地开发跑得通，测试也过，上线才出问题，而且只在首屏闪一下，很难复现。
