CSS Modules 在 Next.js 中未生效，通常源于类名命名不一致或 JavaScript 语法错误：CSS 文件中使用连字符（如 .toolbar-container）是合法的，但在 JS 中 styles.toolbar-container 会被解析为减法运算，必须改为驼峰式（如 .toolbarContainer）并保持两端完全一致。
css modules 在 next.js 中未生效，通常源于类名命名不一致或 javascript 语法错误：css 文件中使用连字符（如 `.toolbar-container`）是合法的，但在 js 中 `styles.toolbar-container` 会被解析为减法运算，必须改为驼峰式（如 `.toolbarcontainer`）并保持两端完全一致。
在 Next.js 的 App Router 架构下，CSS Modules 是推荐的组件级样式方案，但其生效依赖严格的命名约定与导入规范。你遇到的问题——Toolbar.module.css 完全未注入样式——并非构建配置或路径错误所致，而是类名标识符在 CSS 与 JavaScript 两端语义不匹配这一经典陷阱。
? 根本原因分析
CSS 文件中的选择器（如 .toolbar-container）在被 Next.js 编译时，会自动转换为 JavaScript 对象的键名。该转换规则遵循以下原则：
- 连字符 - 会被移除，并将后续字母大写（即 kebab-case → PascalCase）；
- 转换后的键名成为 styles 对象的属性名，必须以合法的 JavaScript 标识符形式访问；
- styles.toolbar-container 在 JS 中等价于 styles.toolbar 减去 container，语法非法，运行时返回 undefined，导致 className 实际为空字符串。
因此，你的原始代码存在如下错配：
/* Toolbar.module.css */
.toolbar-container { /* ✅ 合法 CSS 类名 */ }
/* Toolbar.tsx */
<div classname="{styles.toolbarContainer}"> {/* ✅ 正确访问：驼峰式键名 */}<p>✅ 正确 —— CSS 编译器将 .toolbar-container 映射为 toolbarContainer 键；<br>
❌ 错误 —— 若写成 styles.toolbar-container，JS 解析失败，控制台报 ReferenceError 或静默失效。</p>
<h3>✅ 正确实践示例</h3>
<p><strong>1. 更新 CSS 文件（推荐统一使用驼峰式，避免歧义）</strong> </p>
<pre class="brush:php;toolbar:false;">/* ./components/Toolbar.module.css */
.toolbarContainer {
width: 100%;
display: flex;
flex-direction: row;
align-items: center;
padding: 20px;
background: #808080;
}
2. 组件中严格匹配键名
// ./components/Toolbar.tsx
import styles from './Toolbar.module.css';
export default function Toolbar({ title = 'Social Media App' }) {
return (
<div classname="{styles.toolbarContainer}"> {/* ✅ 精确匹配编译后键名 */}
<h1>{title}</h1>
</div>
);
}
? 提示：你也可保留 .toolbar-container 写法，只要 JS 端始终用 styles['toolbar-container'] 访问（方括号语法绕过标识符限制），但强烈建议统一采用驼峰式命名，既符合 React 生态惯例，又杜绝拼写与语法风险。
⚠️ 其他关键注意事项
- 路径与扩展名必须准确：确保文件名严格为 *.module.css（而非 .css 或 .module.scss 未配预处理器）；
- 仅限客户端组件使用：CSS Modules 不支持在纯服务端组件（Server Component）中导入；若 Toolbar.tsx 未标注 'use client' 且含交互逻辑，需显式声明；
- 无全局污染：CSS Modules 自动哈希类名（如 toolbarContainer__abc123），确保样式作用域隔离；
- 热更新友好：修改 .module.css 后保存，Next.js Dev Server 会即时注入新样式，无需重启。
? 快速验证方法
在组件内添加临时调试输出：
console.log('Styles object:', styles); // 查看实际生成的键名
console.log('Applied class:', styles.toolbarContainer); // 应输出非 undefined 字符串
若 styles.toolbarContainer 为 undefined，说明 CSS 文件未被正确识别或类名不匹配。
✅ 总结
CSS Modules 失效极少由 Next.js 版本或配置引起，绝大多数情况归因于开发者对 CSS-to-JS 映射规则的忽略。牢记三原则：
? CSS 中写 .myClass → JS 中用 styles.myClass；
? CSS 中写 .my-class → JS 中用 styles.myClass（自动转换）或 styles['my-class']（手动访问）；
? 永远不要在 styles.xxx 中使用连字符 —— 这不是 Next.js 的 Bug，而是 JavaScript 语言本身的语法约束。
修复后重新运行 npm run dev，样式将立即生效，且具备完全的局部作用域保障。
