Next.js 中 CSS Modules 必须使用小写 .module.css 后缀，如 card.module.css；import 需在顶层且不可解构，连字符类名自动转驼峰（如 .toolbar-container → styles.toolbarContainer），动态 className 拼接需防 undefined。
文件名必须带 .module.css 后缀
Next.js 仅对 .module.css（或 .module.scss 等）后缀的文件启用 CSS Modules。写成 Button.css、button.module.css（首字母小写但不符合命名惯例）、甚至 Button.Module.css（大写 Module）都可能被忽略，导致样式全局化或完全不生效。
常见错误现象：
- 浏览器中看到原始类名如
container，而非哈希化后的Button_container__xK12j→ 实际是普通全局 CSS - 编译无报错，但样式没渲染 → 极大概率是后缀漏了
module
正确做法：严格使用小写字母 + .module.css，例如 card.module.css、header.module.css。
import 必须在组件顶层且不能解构
CSS Modules 的 import 是编译时行为，不是运行时模块加载。放在函数体、useEffect、if 分支或组件返回值内部都会导致构建失败或样式丢失。
立即学习“前端免费学习笔记（深入）”；
同时，不能解构导入：import { container } from './Card.module.css' 无效，Next.js 不支持按需提取类名属性。
正确写法只有一种：
import styles from './Card.module.css'
然后通过 styles.container 访问 —— 注意不是字符串 "container"，也不是解构后的变量。
连字符类名要转驼峰访问
CSS 文件里写 .toolbar-container，JS 中必须用 styles.toolbarContainer，不能写 styles.toolbar-container（这是 JS 语法错误，- 被解析为减号）。
这个转换是自动的，但前提是：
- CSS 类名拼写完全一致（大小写、连字符位置）
- 类名符合 JS 标识符规范（不能以数字开头，不能含非法符号）
- 没有在
:global(...)块里定义它（否则不会被转换）
例如：.btn-primary:hover → styles.btnPrimaryHover；.is-active → styles.isActive。
避免动态或条件性 className 拼接陷阱
组合多个模块类名时，推荐用模板字符串：`${styles.card} ${styles.shadow}`，而不是数组 join 或第三方库拼接 —— 后者容易漏掉空格或引入 undefined。
条件类名要小心 undefined：
className={`${styles.alert} ${styles[type] || ''}`}
因为 styles.wrongKey 是 undefined，直接拼进去会变成 "alert undefined"，浏览器会忽略整个 class 字符串。
另外，localIdentName 配置虽非必需，但在调试时很有用。可在 next.config.js 中加：
module.exports = { cssModules: { localIdentName: '[path]___[name]__[local]___[hash:base64:5]' } }
这样生成的类名带路径和原始名，一眼能定位来源，但上线前建议关掉或改用更短哈希，避免暴露目录结构。
