Next.js中CSS Modules必须使用.module.css后缀，文件名不规范（如Button.css）将导致样式全局化或失效；import需在顶层，className必须通过styles.xxx访问，动态import和条件import均不支持。
模块化 CSS 文件必须用 .module.css 后缀
Next.js 会根据文件扩展名自动识别模块化行为：只有 .module.css（或 .module.scss 等）才能启用局部作用域。写成 Button.css 或 button.module.css（首字母小写但命名不规范）都可能被忽略或报错。
常见错误现象：
- 样式类名没被哈希化（如浏览器里看到
container而不是Button_container__abc123）→ 实际是全局 CSS，没走模块化 - 编译无报错但样式不生效 → 文件名漏了
module，或 import 路径写错
正确做法：
- 文件命名严格为
xxx.module.css，比如Card.module.css - 在组件中用
import styles from './Card.module.css'，不能解构导入（import { container } from './Card.module.css'无效） - 类名必须通过
styles.xxx访问，直接写className="container"不起作用
import 必须在组件顶层，不能在函数体或条件分支里
模块化 CSS 的 import 是编译时行为，不是运行时加载。放在 useEffect、if 块、或组件返回值内部都会导致构建失败或样式丢失。
立即学习“前端免费学习笔记（深入）”；
错误示例：
export default function Card() {
if (true) {
import styles from './Card.module.css'; // ❌ 报错：Cannot import in conditional
}
return <div className={styles.card}></div>;
}
正确写法：
- import 必须在文件最上方，且在任何
function、const、export定义之前 - 支持 Server Components 和 Client Components，但 Client Component 中仍需顶层 import（
'use client'不影响 import 位置） - 不能动态 import：
import('./Card.module.css')会触发 “CSS cannot be imported dynamically” 错误
类名冲突不会发生，但别手动拼接字符串
CSS Modules 会把 .card { } 编译成类似 Card_card__xyz789 的唯一类名，所以不同组件用同名 class 不会覆盖。
但要注意：
-
className={`${styles.card} ${isActive ? styles.active : ''}`可以，因为styles.card是字符串 -
className="card active"完全无效——这些类名根本不存在于生成的 CSS 中 - 如果要用多个预设状态，推荐用
clsx库：className={clsx(styles.card, isActive && styles.active)} - 不要在 CSS 文件里写
:global(.btn)除非真要穿透作用域；一不小心就退化成全局样式
App Router 下不能在 layout.tsx 里 import 模块化 CSS
app/layout.tsx 是根布局，只接受全局 CSS（如 globals.css）。在这里 import Header.module.css 会报错：“Global CSS cannot be imported from files other than your Custom _app.js or app/layout.tsx”，而模块化 CSS 不属于“Global CSS”。
正确路径是：
- 模块化样式只在具体页面或组件中 import，比如
app/dashboard/page.tsx或src/components/Button.tsx - 如果想复用某组样式逻辑，可封装成组件 + 对应的
.module.css，而不是把样式 import 到 layout 里 - layout 中只能放真正需要全站生效的重置、基础排版、字体等，且必须是
.css（非 module）或 Tailwind 的@tailwind指令
最容易被忽略的一点：模块化 CSS 的哈希后缀是构建时生成的，开发阶段热更新可能偶尔不刷新类名映射——遇到样式突然失效，先试 rm -rf .next 再重启 dev server。
