CSS Modules 在 Next.js 中未生效，通常源于类名命名不一致（如 CSS 中用 .toolbar-container，JS 中却引用 styles.toolbarContainer）或非法 JS 属性访问（如 styles.toolbar-container 因连字符被解析为减法运算），正确做法是统一使用 PascalCase 类名并确保导入路径无误。
css modules 在 next.js 中未生效，通常源于类名命名不一致（如 css 中用 `.toolbar-container`，js 中却引用 `styles.toolbarcontainer`）或非法 js 属性访问（如 `styles.toolbar-container` 因连字符被解析为减法运算），正确做法是统一使用 pascalcase 类名并确保导入路径无误。
在 Next.js 的 App Router 项目中，CSS Modules 是推荐的组件级样式方案，但其生效依赖严格的命名约定与导入规范。你提供的代码中，核心问题在于 CSS 类名与 JavaScript 引用名不匹配，这是导致样式完全不渲染的最常见原因。
? 问题定位：连字符（hyphen）引发的命名断层
你的 CSS 文件定义了：
/* ./components/Toolbar.module.css */
.toolbar-container {
width: 100%;
display: flex;
/* ... 其他样式 */
}而 React 组件中却这样使用：
// ./components/Toolbar.tsx
import styles from "./Toolbar.module.css";
<div className={styles.toolbarContainer}> {/* ❌ 错误：不存在该属性 */}⚠️ 注意：CSS 文件中的 .toolbar-container 在编译后会被自动转换为一个合法的 JavaScript 属性名 —— toolbarContainer（PascalCase），而非保留连字符形式。因此：
立即学习“前端免费学习笔记（深入）”；
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
-
✅ 正确写法（CSS 与 JS 严格对应）：
/* Toolbar.module.css */ .toolbarContainer { /* ... */ }{/* Toolbar.tsx */} <div className={styles.toolbarContainer}> -
❌ 错误写法（即使 CSS 语法合法，JS 无法访问）：
.toolbar-container { } /* 合法 CSS，但生成的 JS 属性名为 toolbarContainer */styles.toolbar-container // ❌ 语法错误：相当于 styles.toolbar - container（减法运算） styles["toolbar-container"] // ⚠️ 技术上可行但不推荐，破坏类型安全且易出错
✅ 正确实践：三步确保 CSS Modules 生效
-
统一使用 PascalCase 类名（推荐）
避免连字符，直接使用驼峰命名，语义清晰且零配置兼容：/* ./components/Toolbar.module.css */ .toolbarContainer { width: 100%; display: flex; flexDirection: row; /* 注意：CSS 属性名仍用 kebab-case，仅选择器名用 PascalCase */ alignItems: center; padding: 20px; backgroundColor: grey; } .toolbarTitle { fontSize: 1.5rem; margin: 0; } -
在客户端组件中正确导入与使用
确保组件是客户端组件（若含交互逻辑），并静态导入模块：// ./components/Toolbar.tsx "use client"; // ✅ 若使用事件、state 等客户端特性，必须声明 import styles from "./Toolbar.module.css"; export default function Toolbar({ title = "Social Media App" }) { return ( <div className={styles.toolbarContainer}> <h1 className={styles.toolbarTitle}>{title}</h1> </div> ); } 验证构建产物与 DevTools
运行 npm run dev 后，打开浏览器开发者工具 → Elements 面板，检查 <div> 元素是否具有类似 className="Toolbar_module__toolbarContainer__abc123" 的哈希化类名；同时在 <head> 中应看到注入的 <style> 块（非 <link>），确认样式已内联注入。
? 常见误区与规避建议
- 不要混用全局 CSS 与 CSS Modules：import './Toolbar.css'（全局）与 import styles from './Toolbar.module.css'（模块）不可互换，前者污染全局，后者作用域隔离。
- 避免在服务端组件（Server Component）中导入 CSS Modules：Next.js 不允许在纯服务端组件中执行样式导入（会报 Error: Cannot import CSS files in Server Components）。如需复用带样式的组件，请确保其为客户端组件（显式添加 "use client"）。
- 路径必须准确且静态：import styles from "./Toolbar.module.css" 中的相对路径需从当前 TSX 文件出发计算，不能使用动态导入（import()）或 require()。
- TypeScript 类型提示增强安全性：启用 @types/node 和 Next.js 内置类型后，styles.toolbarContainer 会在 IDE 中实时校验是否存在，大幅降低拼写错误风险。
? 补充：调试技巧
若仍不生效，可快速排查：
# 1. 检查模块是否被识别为 CSS Module（文件扩展名必须为 .module.css）
ls ./components/Toolbar.module.css
# 2. 查看编译后生成的类型定义（如有 node_modules/.next/types/modules.d.ts）
# 3. 在组件中临时打印 styles 对象
console.log("Styles:", styles); // 应输出 { toolbarContainer: "xxx" }遵循以上规范，CSS Modules 将精准作用于组件，实现样式隔离、避免冲突，并获得完整的 TypeScript 类型支持与构建时哈希化保障。
