next.js 14 中 css modules 类名需用 pascalcase 命名（如.toolbarcontainer），js 中通过 styles.toolbarcontainer 访问；文件必须为 .module.css 后缀，路径须正确；禁止混用不同模块类名，不支持 :global 或 @layer。
Next.js 14 中 CSS Modules 能直接用，但类名映射规则必须吃透
它不是“写了就能生效”，而是靠编译时自动转换类名实现局部作用域。关键在于：CSS 文件里的 .toolbar-container 会被转成 JS 对象上的 toolbarContainer 属性，而不是保留连字符。所以 styles.toolbar-container 是非法 JS 表达式（相当于 styles.toolbar - container），运行时为 undefined，最终 className 变成空字符串——样式自然不出现。
常见错误现象：
- 控制台无报错，但元素没样式、开发者工具里
class属性为空 - 写
styles["toolbar-container"]能临时绕过，但 TypeScript 报错、失去类型提示 - 改用
styles.toolbarContainer后仍无效 → 实际是 CSS 文件里根本没定义.toolbarContainer，只写了.toolbar-container
正确做法：
- CSS 文件中统一用 PascalCase 命名，例如
.toolbarContainer、.buttonPrimary - JS/TS 中严格按驼峰访问：
styles.toolbarContainer - 避免在 CSS 中写
.toolbar-container再指望 JS 里用styles.toolbarContainer—— 虽然 Next.js 确实会做 kebab → Pascal 转换，但一旦拼错或大小写偏差（如.ToolbarContainer），映射就断了
App Router 下的导入路径和文件后缀不能错
Next.js 14 的 App Router 对模块路径更敏感。CSS Modules 必须以 .module.css（或 .module.scss、.module.sass）结尾，且导入路径要相对于当前组件文件。
典型问题：
将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。
- 写成
import styles from './Button.css'→ 不触发 CSS Modules，变成全局样式，可能污染其他组件 - 路径写错，比如组件在
app/components/Button.tsx，却从./Button.module.css导入，而文件实际在app/components/styles/Button.module.css - 在
app/layout.tsx或app/page.tsx中误用 CSS Modules —— 这些是路由级文件，推荐用全局 CSS 或 Tailwind
建议：
- 组件专属样式一律放在同级目录，命名严格为
ComponentName.module.css - 使用 VS Code 的路径自动补全 + 鼠标悬停查看解析路径，避免手误
- Storybook 中同样支持
.module.css零配置，无需额外 Webpack 设置
组合类名和动态 class 处理要小心
CSS Modules 支持 composes（仅限 .css，不支持 SCSS），也支持用模板字符串或 clsx 拼接多个模块类。但注意：所有参与拼接的类名都必须来自同一个 styles 对象，不能混用不同模块的类名。
容易踩的坑：
-
className={`${styles.card} ${styles.shadow}`✅ 正确，两者都来自同一模块 -
className={`${styles.card} ${otherStyles.container}`❌ 危险，不同模块的哈希前缀不同，组合后可能被 CSS 优先级或构建顺序干扰 - 用
clsx(styles.card, isHovered && styles.cardHover)✅ 推荐，语义清晰且类型安全（需安装clsx并配好类型定义） - 在
style属性里写内联样式替代 class？不推荐 —— 失去 CSS Modules 的局部作用域和复用能力
不要试图在 CSS Modules 里写 :global 或 @layer
Next.js 的 CSS Modules 实现基于 PostCSS 和内置 loader，不支持原生 CSS 的 :global() 伪类或 @layer（除非你手动配了插件）。想覆盖第三方库样式或做全局重置，应该：
- 用
app/globals.css放全局规则（如*, *::before, *::after { box-sizing: border-box; }） - 需要局部穿透时，改用
style属性或!important（慎用） - 想复用基础样式？用
composes（CSS）或提取共用 class 字符串常量（TS）
真正复杂的地方从来不是“怎么写”，而是“什么时候不该用”。CSS Modules 适合组件级封装，但一旦涉及主题切换、暗色模式或跨组件状态联动，很快就会撞上它的边界——这时候该切 Tailwind 或考虑 CSS-in-JS 方案，而不是硬塞 composes 和嵌套 :is()。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
