css modules是react官方脚手架开箱即用的局部作用域方案，必须将文件命名为.module.css（如button.module.css）并以import styles from './x.module.css'方式引入，通过styles.xxx动态绑定classname实现样式隔离，零运行时开销。
直接用 import styles from './Button.module.css' 就能获得局部作用域，不需要改组件结构、不依赖额外库、零运行时开销——这是 React 官方脚手架开箱即用的能力，不是第三方方案。
为什么必须把 .css 改成 .module.css？
Create React App（以及大多数现代 React 脚手架）默认只对匹配 /\.module\.css$/ 的文件启用 CSS Modules。如果你写 import styles from './Button.css'，哪怕内容一模一样，webpack 也不会做类名哈希，结果还是全局样式。
- 文件名必须含
.module.，比如Button.module.css、Header.module.scss -
.module.less、.module.styl同样有效，只要 loader 配置支持 - 不区分大小写，但推荐小写保持一致性
- 重命名后，旧的
import './Button.css'引用会报错，必须同步改成import styles from './Button.module.css'
className={styles.xxx} 是唯一合法用法
CSS Modules 导出的是一个对象，键是原始类名，值是编译后的唯一哈希类名（如 Button_button__axY7）。它不支持字符串拼接、不支持动态计算类名，也不接受 styleName 这种非标准属性。
- ✅ 正确：
<button classname="{styles.button}">Click</button> - ❌ 错误：
<button stylename="button">Click</button>（这是react-css-modules的语法，已过时且不兼容 CRA） - ❌ 错误：
className="button"（绕过 modules，退化为全局样式） - ❌ 错误：
className={styles['btn-' + type]}（TS 会报错，运行时可能为undefined）
如果真要条件组合，用 clsx 或 classnames： className={clsx(styles.button, props.primary && styles.primary)}。
遇到 undefined 类名别慌，先查三件事
常见现象是元素没渲染出样式，React DevTools 里看到 className="" 或 className="undefined"。这几乎一定是引用方式错了。
- 检查文件是否真的重命名为
.module.css（不是.modules.css或.mod.css） - 检查 import 路径是否拼写正确，特别是大小写（Linux/macOS 下
button.module.css≠Button.module.css） - 检查 CSS 文件里有没有写错类名，比如
.btn却用了styles.button（TS 不会报错，但值是undefined）
注意：react-css-modules 会报运行时警告，但原生 CSS Modules 不会——它安静地返回 undefined，这点非常容易忽略。
TypeScript 项目里记得补类型声明
否则 styles.xxx 会被 TS 当作 any，失去类型保护和自动补全。
在项目根目录下任意 .d.ts 文件（如 src/react-app-env.d.ts）中添加：
declare module '*.module.css' {
const classes: { [key: string]: string };
export default classes;
}
declare module '*.module.scss' {
const classes: { [key: string]: string };
export default classes;
}
如果用了 Sass 嵌套或 @use，确保你的 css-loader 配置启用了 modules.getLocalIdent，否则嵌套规则可能无法正确生成类名。
最常被跳过的其实是文件命名和 import 路径的一致性——这两个地方错一个字符，样式就完全失效，而且没有任何构建错误提示。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
