最常见原因是硬编码字符串类名与CSS Modules哈希类名不匹配；必须通过import styles from './X.module.css'并使用styles.primary访问，且文件名须含.module.css后缀。
className硬编码字符串导致样式不生效
最常见的情况是：你在Button.module.css里写了.primary，但在 JSX 中写了className="primary"。CSS Modules 编译后类名变成类似Button_primary__abc123，而"primary"这个字符串根本没被哈希处理，浏览器自然找不到对应样式。
必须通过导入对象访问：import styles from './Button.module.css'，然后用styles.primary；不能用require('./Button.module.css')（它返回路径字符串）；也不能漏掉.module.css后缀——否则构建工具不触发 CSS Modules 处理。
- 检查 DevTools 元素面板：如果
class属性为空或显示"primary"但无样式，基本就是这个原因 - 动态拼接时禁止混用：
{`${styles.btn} ${isPrimary ? 'primary' : ''}`❌，应统一走styles：{`${styles.btn} ${isPrimary ? styles.primary : ''}`✅ - 多条件推荐用
clsx：className={clsx(styles.btn, isPrimary && styles.primary)}
composes复用样式时路径或作用域错乱
composes用于继承基础样式（比如.btn--large复用.btn），但它对路径和模块状态很敏感。常见失效原因是：被composes的源文件没启用 CSS Modules，或者路径用了别名但构建工具未识别。
例如：.large { composes: btn from './BaseButton.module.css'; }，如果BaseButton.module.css实际叫BaseButton.css，或者配置了@styles别名但css-loader没配resolve.alias，就会静默失败。
立即学习“前端免费学习笔记（深入）”；
适用于用户提出以下需求时：“构建赢回活动（win-back campaign）”、“重新激活已流失订阅者（re-engage lapsed subscribers）”、“执行重新授权 / 重新同意（re-permission / re-consent）清理”或“清理无效联系人列表（sunset my dead list）”；输出一个闭环式再激活方案——包括：流失用户群组（lapsed-cohort）定义、分阶段优惠阶梯（staged offer ladder）、重新授权（re-consent / re-p
- Vite 用户注意：
composes在 Vite 4.3+ 才稳定支持，旧版本会忽略整行规则 - 被
composes的文件必须是.module.css后缀，且本身也经过 CSS Modules 处理 - 不支持绝对路径别名（如
@/styles/Base.module.css），除非你确认 css-loader 的alias配置已生效并被其插件识别
:global()写法位置不对或嵌套过深
想覆盖第三方组件（如 Ant Design）内部样式时，很多人直接在自己的.module.css里写:global(.ant-btn) { color: red; }，却发现无效。问题往往出在作用域层级或加载顺序上。
CSS Modules 默认把所有规则转为局部，:global()只对外层选择器生效。如果你写成:global(.ant-btn:hover)，hover 状态可能仍被组件库原始样式覆盖；更稳妥的是把整个规则块包进:global{}，并确保你的 CSS 文件在组件库 CSS 之后加载。
- 正确写法：
:global { .ant-btn { color: red; } }，而不是.my-wrapper :global(.ant-btn) - Next.js 或 SSR 场景下，
:global规则若依赖服务端生成的 class 名，可能 hydrate 不一致，建议仅用于确定不会 SSR 的交互区域 - 避免在
:global里写太具体的选择器（如.ant-btn.ant-btn-primary），优先靠提高加载顺序和 specificity 解决
服务端渲染中styles对象为空导致样式闪动
在 Next.js 或 RSC 环境中，import styles from './X.module.css'在服务端执行时返回空对象{}，因为 Node 环境无法解析 CSS 文件生成哈希映射。结果客户端 hydrate 时 class 名从空变成真实哈希值，造成样式短暂丢失或布局跳变。
这不是 CSS Modules 本身的问题，而是构建链路在服务端缺失 CSS 处理能力。目前没有零成本解法，但可以缓解：
- 用
useEffect延迟挂载依赖样式的 DOM（适合非首屏内容） - 改用
styled-jsx或emotion这类支持 SSR 的 CSS-in-JS 方案（但失去类名可读性） - 关键样式抽到全局 CSS 文件中，用
:global包裹，绕过模块化流程
真正难处理的是那些既要局部隔离、又必须 SSR 的场景——这时候得接受一个事实：CSS Modules 天然偏向 CSR，强 SSR 需求下，它只是个起点，不是终点。
