根本原因是CSS Modules将类名哈希化后，JSX中硬编码的字符串类名（如"primary"）与实际生成的哈希类名（如Button_primary__abc123）不匹配；必须通过import styles from './X.module.css'并使用styles.primary访问，且文件须为.module.css后缀。
为什么className加了但样式没生效？
根本原因不是写错了类名，而是 CSS Modules 默认把类名哈希化后，JSX 中写的字符串类名和实际生成的类名不匹配。比如你在 Button.module.css 里写了 .primary，编译后可能变成 Button_primary__abc123，而你若在 JSX 中硬编码 className="primary"，浏览器根本找不到这个类。
常见错误现象：style 标签里能看到规则，元素上却没对应 class；DevTools 中 class 属性为空或显示原始名但无样式。
- 必须通过
import styles from './Button.module.css'导入对象，再用styles.primary - 不能用
require('./Button.module.css')（返回的是字符串路径，不是类名映射） - 确保文件名含
.module.css后缀，否则 Webpack/Vite 不会启用 CSS Modules 处理
composes 覆盖失效的典型场景
想复用基础样式（比如 btn）再叠加变体（btn--large），用 composes: btn from './BaseButton.module.css'; 是对的，但容易踩两个坑：
-
composes只支持同级或相对路径导入，不支持别名（如@styles/BaseButton.module.css），除非你配了resolve.alias并确保 CSS Modules 插件识别它 - 如果被
composes的源文件本身也用了 CSS Modules，它的类名会被二次哈希——但composes引用的是编译前的原始名，所以必须确保导入路径指向的是「已处理为模块」的文件（即带.module.css后缀） - Vite 用户注意：
composes在 Vite 4.3+ 才稳定支持，旧版本会静默忽略
动态类名拼接导致哈希断裂
写 className={`${styles.btn} ${isPrimary ? 'primary' : ''}` 是错的——'primary' 是字面量，不会被 CSS Modules 处理，自然没样式。
立即学习“前端免费学习笔记（深入）”；
- 正确做法是统一走
styles对象：className={`${styles.btn} ${isPrimary ? styles.primary : ''}` - 多个条件组合时，推荐用
clsx或classnames库：className={clsx(styles.btn, isPrimary && styles.primary, isDisabled && styles.disabled)} - 避免在模板字符串里混用
styles.xxx和纯字符串，极易漏掉引号或拼写错误
服务端渲染（SSR）下样式丢失
Next.js 或 RSC 环境中，CSS Modules 的 styles 对象在服务端是空对象（{}），因为 CSS 文件无法在 Node 环境解析出类名映射，导致客户端 hydrate 时 class 名不一致、样式闪动或失效。
- Next.js 13+ 推荐改用
app/目录下的client components+use client，确保 CSS Modules 只在浏览器执行 - 如果必须 SSR，需配合
styled-jsx或emotion等支持 SSR 的方案，CSS Modules 本身不解决该问题 - 检查
document.head是否注入了对应<style>标签——没有的话，说明 CSS 文件未被正确 import 或构建配置漏掉了 CSS 提取逻辑
styles 对象访问，任何绕过它的字符串操作都会断掉哈希链。最容易被忽略的是动态拼接和 SSR 场景下的执行时机差异。 
