保罗的小宇宙
·
记一次升级 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。
延伸解读
CSS Hash 不一致的原因
在将 Nuxt 从 3 升级到 4 的过程中，CSS 样式丢失的根本原因是 SSR 和客户端构建的 CSS Hash 不一致。这种不一致主要源于 Vite 在处理 CSS Modules 时，SSR 和客户端构建对文件路径的处理方式不同，导致生成的类名哈希不一致。
解决方案的有效性
将文件后缀从 .less 改为 .css 是解决 CSS 样式丢失问题的有效方法。这一改变避免了预处理器流程的影响，使得 SSR 和客户端构建的哈希一致，从而确保样式正常应用。相较于修改配置，后缀名的简单调整更为直接和高效。
对项目的影响
如果项目中仍使用 .module.less 或 .module.scss 文件，可能会面临类似的哈希不一致问题。建议开发者在遇到样式丢失时，考虑统一使用 .module.css 文件，或在配置中添加 generateScopedName，以确保样式正常渲染。
延伸问答
升级 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 处理方式不同，导致哈希不一致。
