React中CSS Modules需严格使用.module.css后缀，文件名必须为xxx.module.css而非xxx.css或xxx-modules.css；导入后须通过styles.className使用哈希化类名，不可直接写字符串类名。
React中CSS Modules的文件命名和自动识别机制
React（特别是Create React App）对CSS Modules的支持依赖文件名后缀，不是靠配置开关。只要文件名以 .module.css 结尾（如 Button.module.css），Webpack 就会默认启用 CSS Modules 处理——不需要手动修改 webpack 配置，也不需要在 import 语句里加特殊标识。
常见错误是只改了内容、没改后缀：比如写了模块化样式但文件仍叫 Button.css，这时所有类名仍全局生效，import styles from './Button.css' 得到的是空对象或普通字符串。
-
.module.css是硬性约定，.module.scss/.module.less同理有效 - 不支持
index.module.css这种写法（某些旧版 CRA 会报错，新版虽可导入但易混淆） - 文件名中的
module必须紧贴点号，不能是button-modules.css或button.css.module
如何正确 import 并使用生成的局部类名
CSS Modules 会把每个类名编译成唯一哈希值，所以必须通过 JS 对象解构来使用，不能直接在 JSX 中写死字符串类名。
例如 Button.module.css 内容为：
立即学习“前端免费学习笔记（深入）”；
.container { padding: 8px; }<br>.primary { background: #007bff; }
对应导入和使用方式是：
import styles from './Button.module.css';<br><br>function Button() {<br> return <button className={styles.container + ' ' + styles.primary}>Click</button>;<br>}
注意：styles.container 是运行时计算出的真实类名（如 Button_container__abc123），不是原始字符串 "container"。
- 不能写
className="container"—— 这会丢失模块化效果 - 多个类名拼接推荐用
clsx或class-variance-authority等工具，避免手拼空格出错 - 如果需要动态切换，确保变量是已定义的 key，否则
styles[unknownVar]会是undefined，导致 class 丢失
为什么有时 className 没生效？检查这三点
最常遇到“样式不渲染”，往往不是语法问题，而是环境或路径细节被忽略。
- 确认文件确实保存为
.module.css（VS Code 状态栏右下角显示语言模式是否为 “CSS Modules”） - 检查 import 路径是否正确——CRA 默认不支持别名（如
@/styles），必须用相对路径./xxx.module.css - 浏览器开发者工具中查看元素的
class属性：如果看到原始类名（如container）而非带哈希的（如Button_container__xyz789），说明文件根本没走 CSS Modules 流程，大概率后缀或路径错了
与普通 CSS 并存时的注意事项
一个项目里可以同时存在 .css（全局）和 .module.css（局部）文件，但要注意它们的导入行为完全不同。
比如：
import './global.css'; // 全局注入，无返回值<br>import styles from './Button.module.css'; // 返回类名映射对象
一旦误把 .module.css 当作普通 CSS 导入（即不接收返回值），就会失去所有类名；反之，把普通 .css 当模块导入（import xxx from './xxx.css'），则 xxx 通常是空对象或 {}，取属性会 undefined。
- 编辑器开启文件后缀高亮能快速区分：.module.css 文件通常有不同颜色标记
- ESLint 插件
eslint-plugin-import可配规则禁止import styles from './xxx.css'这类明显错误写法 - 服务端渲染（SSR）场景下，需确保构建工具（如 Next.js）也启用了 CSS Modules 支持，否则客户端和服务端类名哈希不一致，触发 hydration mismatch
.modlue.css），或者从别的项目复制文件时没重命名。建议把创建新样式文件的操作固化为一条命令脚本，或者在 IDE 中配置文件模板。 
