Next.js 开发时 className 频繁变化是 CSS Modules 默认行为，因 HMR 重算哈希导致；根本解法是将样式逻辑移至 Client Component，禁用 Server Component 中 styles.xxx 调用，避免 hydration mismatch。
开发环境类名每次刷新就变，不是 bug，是 CSS Modules 默认行为；但可以稳定它，关键在控制哈希生成逻辑，而不是关掉哈希。
为什么 Next.js 开发时 className 总在变
CSS Modules 的哈希依赖构建时的随机 salt（比如 Webpack 的热更新时间戳），每次 HMR 或重启 dev server 都会重算。比如 Button_button__abc123 下次可能变成 Button_button__def456。这导致 DevTools 断点失效、手动覆盖样式错位、截图标注失准。
- 这不是配置漏了，而是默认设计——生产环境用 contenthash 是稳定的，开发环境则优先考虑 HMR 速度
- Next.js 没暴露 css-loader 配置入口，不能直接改
localIdentName，得走官方支持路径 - 别试图在
app/目录的 Server Component 里 import .module.css —— 它根本不会执行模块化逻辑，styles是空对象
Next.js 中稳定开发类名的可行方案
Next.js 官方不鼓励自定义哈希规则，但提供了两个实际可用的出口：
- 在
vite.config.ts（若你用 Vite + Next.js 混合架构）中配css.modules.generateScopedName，例如'[name]__[local]___[hash:base64:5]'，并确保没启用dev.ssr导致服务端/客户端不一致 - 更通用的做法：用
next.config.js启用experimental.cssImport（仅限旧版 Next.js），或直接迁移到styled-jsx+clsx组合——它不依赖哈希，也无 SSR 类名错位风险 - 如果坚持用 CSS Modules，必须把所有样式导入限制在
"use client"组件内，且确保文件后缀是.module.css，否则styles对象无法正确解析
服务端渲染（SSR）下类名对不上的根因
Node 环境和服务端构建用的哈希 seed 不一致，导致 HTML 渲染出的 button__xyz 和浏览器 hydrate 时计算出的 button__abc 不匹配，React 报 warning 甚至样式闪动。
立即学习“前端免费学习笔记（深入）”；
- Next.js 的 App Router 默认在服务端不解析 .module.css 的类名映射，
styles是空对象，所以服务端根本没生成任何类名 - 客户端 hydrate 时才真正读取 CSS 文件并生成哈希，必然和 SSR 输出不一致
- 唯一稳妥解法：不在 Server Component 里依赖
styles.xxx做 class 名拼接；把样式逻辑完全交给 Client Component 处理 - 若需服务端有基础样式，用
:global写重置或工具类，例如:global(.text-sm) { font-size: 0.875rem; }
真正麻烦的不是哈希变不变，而是你是否在 Server Component 里写了 className={styles.button} 这种代码——它在服务端返回空字符串，客户端再补上，必然触发 hydration mismatch。这点最容易被忽略，也最难调试。
