保罗的小宇宙
·
记一次升级 Nuxt 4 的诡异问题
内容提要
将 Nuxt 从 3 升级到 4 后，CSS 样式丢失，因 SSR 和客户端构建的 CSS Hash 不一致。通过将文件后缀改为 .css，成功解决了问题，最终确认使用 .module.css 避免了哈希不一致。
关键要点
-
将 Nuxt 从 3 升级到 4 后，CSS 样式丢失，原因是 SSR 和客户端构建的 CSS Hash 不一致。
-
问题出在 CSS Modules 的类名哈希在 SSR 构建和客户端构建之间不一致。
-
修复方案是在 nuxt.config.ts 中显式配置 generateScopedName，以确保两次构建使用相同的规则生成类名。
-
修改文件后缀名从 .less 改为 .css 也能解决问题，因为这样避免了预处理器流程的影响。
-
Vite 在处理 CSS 预处理器与 CSS Modules 组合时存在长期的 SSR 一致性问题。
-
使用 .module.css 可以绕开预处理器流程，避免附加的标记导致哈希不一致。
-
如果项目中还有其他 .module.less/.module.scss 的组件，添加简单的 generateScopedName 也能解决类似问题。
-
要彻底修复 Bug，需要将所有的 .module.less 文件改为 .module.css，或修改 generateScopedName 配置。
-
Less 逐渐被淘汰，建议拥抱更新的技术，如 CSS in JS。
延伸问答
升级 Nuxt 4 后 CSS 样式丢失的原因是什么？
CSS 样式丢失是因为 SSR 和客户端构建的 CSS Hash 不一致。
如何解决 Nuxt 4 中 CSS Hash 不一致的问题？
可以在 nuxt.config.ts 中配置 generateScopedName，确保两次构建使用相同的规则生成类名。
将文件后缀从 .less 改为 .css 有什么效果？
修改后缀为 .css 可以避免预处理器流程的影响，从而解决 CSS Hash 不一致的问题。
使用 .module.css 有什么好处？
.module.css 可以绕开预处理器流程，避免附加的标记导致哈希不一致。
如果项目中还有其他 .module.less 文件，应该怎么处理？
可以添加简单的 generateScopedName 配置，或者将所有 .module.less 文件改为 .module.css。
为什么 Vite 在处理 CSS 预处理器时会出现一致性问题？
Vite 在 SSR 和客户端构建中对中间产物的 id 处理方式不同，导致哈希不一致。
