Next.js 14 中 CSS Modules 样式不生效的根源在于类名映射失败、导入时机错误（需标记"use client"）及文件命名不规范（必须为.module.css且遵循BEM/驼峰规则）。
Next.js 14 中 CSS Modules 默认开箱即用，但「能 import」不等于「样式生效」——真正卡住人的，是类名映射、导入时机和文件命名这三处细节。
为什么 styles.button 是 undefined？
这不是路径写错，而是构建链路在类名转换环节断了。Next.js 把 .button 编译成 styles.button，但前提是：CSS 文件里真有这个类，且它没被 :global 逃逸、没被嵌套选择器包裹、也没写在 @layer 或媒体查询外层。
-
.button✅ 正确：会被编译为styles.button -
.toolbar-container✅ 合法 CSS，但 JS 中必须写styles.toolbarContainer（连字符自动转驼峰） -
div .button❌ 真嵌套写法，CSS Modules 不支持，该规则不会映射到styles对象 -
:global(.reset)❌ 整条规则脱离模块作用域，styles.reset永远是undefined
App Router 下 import styles from './Button.module.css' 报错？
错误信息通常是 Module not found: Can't resolve './Button.module.css' —— 这几乎一定是组件没标记为 Client Component。
- Server Component（默认）中 import .module.css → 构建阶段直接跳过，报错或静默失败
- 必须在组件顶部加
"use client"才能触发 CSS Modules loader -
app/layout.tsx和app/page.tsx是 Server Component，不能在这里 import 样式文件 - 哪怕只是
Button.tsx里 import，只要它被 Server Component 直接引用，也得自己声明"use client"
.module.css 文件名和目录结构怎么写才不踩坑？
Next.js 14 的 App Router 对文件名和位置极其敏感，大小写、连字符、路径层级全影响类名生成和哈希稳定性。
立即学习“前端免费学习笔记（深入）”；
- 文件名必须含
.module.css后缀，Button.css或Button.scss会被当全局样式处理，import 会报错 - 目录名要小写+中划线，且与块名一致：比如
components/user-profile/UserProfile.module.css→ 块名是user-profile，不是UserProfile - BEM 类名必须以块名开头：
.user-profile、.user-profile__avatar、.user-profile--large，不能写.avatar或.large - 访问修饰符类时必须用方括号：
styles['user-profile--large']，因为--在 JS 中非法，styles.user-profile--large是语法错误
最常被忽略的一点：BEM 修饰符和元素类名在 JS 中无法用点号访问，必须走字符串键；而很多人只记得改 CSS 名，忘了在组件里同步改引用方式。
