CSS Modules生效需精准配置：Webpack中modules:true须限定于.module.css文件，Vite需确保未禁用css.modules，Next.js的app目录须在Client Component中导入，styles为undefined通常因loader未执行modules流程。
CSS Modules 不是开个开关就自动生效的——关键在 modules 配置项是否真正作用于你的 .module.css 文件，且没被其他规则覆盖。
Webpack 中 modules: true 必须精准匹配 .module.css
很多人配了 modules: true 却没效果，是因为它被写在了全局 /\.css$/ 规则里。这会导致：
– 第三方库（如 antd、normalize.css）的样式也被模块化，按钮变灰、重置失效
– 所有类名强制哈希，连 html 或 body 上的全局样式都失灵
正确做法是只对带 .module.css 后缀的文件启用：
- 用
test: /\.module\.css$/显式限定范围 - 或更稳妥地用
modules: { auto: true }（Webpack 5+），它会根据文件名 + import 方式双重判断 -
localIdentName至少保留[local]，否则类名失去局部性，比如写成[hash:5]就等同于全局随机名
Vite 默认开启但可能被手动关掉
Vite 从 4.0 起对 .module.css 默认启用 CSS Modules，但如果你在 vite.config.ts 里写了：
立即学习“前端免费学习笔记（深入）”；
css: { modules: false }
那所有模块化行为都会被禁用，连 import styles from './Button.module.css' 都会返回空对象。
检查点：
- 删掉
css.modules的显式false配置（不配 = 默认开启） - 确认文件后缀确实是
.module.css，不是.css或.scss（除非你额外配了scss: { modules: true }） - 如果用了别名（如
@/styles/Button.module.css），确保别名解析不影响后缀识别
Next.js app 目录下 import 失败的隐藏条件
Next.js 13.2+ 在 app/ 目录中，import CSS 文件必须发生在 Client Component 中。Server Component 里执行 import './Button.module.css' 会直接报错：
Module not found: Can't resolve './Button.module.css'
这不是路径问题，而是构建阶段被跳过。解决方式只有两个：
- 把组件标记为
"use client" - 或者改用
layout.tsx或page.tsx等服务端文件里不 import 样式，只在 Client Component 里导入并使用styles对象
为什么 styles.button 是 undefined？常见断点位置
看到 className={styles.button} 渲染为空，大概率不是 JS 写错了，而是构建链路在某个环节漏掉了 modules 处理：
-
Button.module.css文件里写了:global(.reset)，但外层没套局部选择器，导致整条规则逃逸，无法映射到styles对象 - 用了 PostCSS 插件（如
postcss-import），但没配置modules: true透传给postcss-modules - 开发服务器热更新卡住，JS 已读取新
styles对象，但 CSS 没重注入——此时硬刷页面无效，得重启npm run dev
最省事的验证方式：临时加一行 console.log(styles)，看输出是不是空对象或只有 toString 方法——如果是，说明 loader 根本没跑 modules 流程。
