开启CSSModules，防止样式冲突

CSS Modules 并非简单开关就能生效，其核心在于精准配置：Webpack 必须通过 `test: /\.module\.css$/` 或 `modules: { auto: true }` 严格限定作用范围，避免误模块化第三方样式；Vite 虽默认支持，但易被 `css.modules: false` 意外关闭；Next.js 的 app 目录则强制要求在 Client Component 中导入，Server Component 中直接报错。当 `styles.button` 为 undefined 时，往往不是代码错误，而是构建链路中断——从文件后缀、PostCSS 配置到热更新卡顿，每个环节都可能让 modules 流程悄然失效。掌握这些隐藏细节，才能真正用好 CSS Modules，彻底告别样式冲突与全局污染。

CSS Modules 不是开个开关就自动生效的——关键在 modules 配置项是否真正作用于你的 .module.css 文件，且没被其他规则覆盖。

Webpack 中 modules: true 必须精准匹配 .module.css

很多人配了 modules: true 却没效果，是因为它被写在了全局 /\.css$/ 规则里。这会导致：
– 第三方库（如 antd、normalize.css）的样式也被模块化，按钮变灰、重置失效
– 所有类名强制哈希，连 html 或 body 上的全局样式都失灵

正确做法是只对带 .module.css 后缀的文件启用：

• 用 test: /\.module\.css$/ 显式限定范围
• 或更稳妥地用 modules: { auto: true }（Webpack 5+），它会根据文件名 + import 方式双重判断
• localIdentName 至少保留 [local]，否则类名失去局部性，比如写成 [hash:5] 就等同于全局随机名

Vite 默认开启但可能被手动关掉

Vite 从 4.0 起对 .module.css 默认启用 CSS Modules，但如果你在 vite.config.ts 里写了：

css: { modules: false }

那所有模块化行为都会被禁用，连 import styles from './Button.module.css' 都会返回空对象。

检查点：

• 删掉 css.modules 的显式 false 配置（不配 = 默认开启）
• 确认文件后缀确实是 .module.css，不是 .css 或 .scss（除非你额外配了 scss: { modules: true }）
• 如果用了别名（如 @/styles/Button.module.css），确保别名解析不影响后缀识别

Next.js app 目录下 import 失败的隐藏条件

Next.js 13.2+ 在 app/ 目录中，import CSS 文件必须发生在 Client Component 中。Server Component 里执行 import './Button.module.css' 会直接报错：

Module not found: Can't resolve './Button.module.css'

这不是路径问题，而是构建阶段被跳过。解决方式只有两个：

• 把组件标记为 "use client"
• 或者改用 layout.tsx 或 page.tsx 等服务端文件里不 import 样式，只在 Client Component 里导入并使用 styles 对象

为什么 styles.button 是 undefined？常见断点位置

看到 className={styles.button} 渲染为空，大概率不是 JS 写错了，而是构建链路在某个环节漏掉了 modules 处理：

• Button.module.css 文件里写了 :global(.reset)，但外层没套局部选择器，导致整条规则逃逸，无法映射到 styles 对象
• 用了 PostCSS 插件（如 postcss-import），但没配置 modules: true 透传给 postcss-modules
• 开发服务器热更新卡住，JS 已读取新 styles 对象，但 CSS 没重注入——此时硬刷页面无效，得重启 npm run dev

最省事的验证方式：临时加一行 console.log(styles)，看输出是不是空对象或只有 toString 方法——如果是，说明 loader 根本没跑 modules 流程。

今天关于《开启CSSModules，防止样式冲突》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！