根本原因是未启用css modules或文件名未按.module.css命名；create react app需后缀正确，webpack需配置modules: { mode: 'local' }，vite需检查generatescopedname，且必须import styles from './x.module.css'解构对象而非默认导入。
React里用CSS Modules为什么样式不生效
根本原因是没在构建配置里启用CSS Modules，或者文件名没按约定命名。Create React App默认支持，但必须用.module.css后缀；自建Webpack则要显式配置modules: true和localIdentName。
常见错误现象：className="button"写对了，但浏览器里渲染出的class却是button原样，没被哈希化——说明CSS Modules根本没启用。
- 检查文件名是否为
Button.module.css，不是Button.css - Create React App下无需额外配置，但改后缀是硬性要求
- Webpack 5+中若手动配置
css-loader，需确保modules: { mode: 'local' } - Vite用户需确认
css.modules.generateScopedName是否被意外覆盖
import样式时解构写法容易漏掉default
CSS Modules导出的是一个对象，不是默认导出一个字符串。写成import styles from './Button.module.css'是对的；但有人误写成import { button } from './Button.module.css'，结果button是undefined。
使用场景：组件内需要多个类名组合，比如按钮主类+禁用态+加载态，必须从对象里取值。
立即学习“前端免费学习笔记（深入）”；
Angel工作室企业网站管理系统全DIV+CSS模板，中英文显示，防注入sql关键字过滤，多浏览器适应，完美兼容IE6-IE8,火狐，谷歌等符合标准的浏览器，模板样式集中在一个CSS样式中，内容与样式完全分离，方便网站设计人员开发模板与管理。系统较为安全，以设计防注入，敏感字符屏蔽。新闻，产品，单页独立关键字设计，提高搜索引擎收录。内置IIS测试，双击打启动预览网站 Angel工作室企业网站
-
import styles from './Button.module.css'→ 正确，得到{ button: 'Button_button__abc123', disabled: 'Button_disabled__def456' } -
import * as styles from './Button.module.css'→ 也可行，但不如第一种直观 - 别用
import button from './Button.module.css'，这是把整个模块当默认导出，实际没有
全局样式和局部样式混用时的冲突风险
CSS Modules只作用于它处理的文件，但:global和:local可以穿插使用。问题常出在第三方UI库或重置样式（如normalize.css）被错误套上Modules——导致全局选择器失效或被哈希污染。
性能影响不大，但维护成本陡增：你改了一个:global(.btn)，可能发现所有按钮都变了，却查不到源头。
- 第三方CSS（如
antd/dist/antd.css）必须用普通import 'antd/dist/antd.css'，不能加.module - 想在
.module.css里写全局规则？用:global(.highlight) { color: red; }，别直接写.highlight - 避免在同一个文件里频繁切换
:global和:local，可读性会断崖下跌
服务端渲染（SSR）时className不匹配的Hydration警告
开发时没报错，上线SSR后控制台出现Prop `className` did not match，大概率是CSS Modules生成的哈希名在客户端和服务端不一致。根源在于localIdentName里用了[hash]但没固定contentHash种子，或服务端构建时环境变量不同。
兼容性影响明显：React 18严格模式下会直接中断Hydration，首屏闪动或白屏。
- Webpack中确保
localIdentName含[contenthash:8]而非[hash] - Next.js用户注意
next.config.js中cssModules: true已弃用，应改用postcss.config.js配合postcss-modules - 服务端和客户端构建必须共用同一份CSS输出，禁止分别打包两套
.module.css
最麻烦的点往往藏在构建工具链深处——比如Babel插件提前处理了import语句，或Monorepo中多个包共享了未隔离的CSS loader实例。
