保罗的小宇宙
·
记一次升级 Nuxt 4 的诡异问题
内容提要
将 Nuxt 从 3 升级到 4 后，CSS 样式丢失，原因是 CSS Modules 的哈希不一致。通过将文件后缀改为 .css，成功解决了问题，避免了复杂配置。最终确认所有 .module.less 文件应改为 .module.css，以彻底修复该 Bug。
关键要点
-
将 Nuxt 从 3 升级到 4 后，CSS 样式丢失，原因是 CSS Modules 的哈希不一致。
-
问题出在 styles.module.less 文件，客户端和服务端生成的 CSS Hash 不一致。
-
修复方案是在 nuxt.config.ts 中配置 generateScopedName，确保两次构建使用相同的规则生成类名。
-
修改文件后缀名为 .css 也能解决问题，避免复杂配置。
-
Vite 在处理 CSS 预处理器时，SSR 和客户端构建的路径处理方式不同，导致哈希不一致。
-
将所有 .module.less 文件改为 .module.css 是彻底修复该 Bug 的方法。
-
使用 generateScopedName 解决方案可以绕过哈希不一致的问题，但不如直接修改后缀名简单。
-
问题的触发条件是 .module.less 文件只被单个页面引用，导致 Vite 生成的模块 ID 不一致。
-
总结：彻底修复需要将所有 .module.less 文件改为 .module.css，或修改 generateScopedName 配置。
延伸解读
CSS Modules 的哈希问题
在将 Nuxt 从 3 升级到 4 的过程中，CSS Modules 的哈希不一致是导致样式丢失的主要原因。这一问题在 SSR 和客户端构建中表现得尤为明显，开发者需要注意在使用 CSS 预处理器时，可能会遇到类似的哈希不一致问题。
解决方案的选择
文章中提到的两种解决方案：修改文件后缀名和配置 generateScopedName，各有优缺点。直接修改后缀名为 .css 是最简单直接的方式，而配置 generateScopedName 则需要更多的配置和理解。开发者应根据项目需求选择合适的方案。
Vite 的构建机制
Vite 在处理 CSS 预处理器时，SSR 和客户端构建的路径处理方式不同，导致哈希不一致。了解 Vite 的构建机制对于避免类似问题至关重要，尤其是在使用 LESS 或 SCSS 等预处理器时，开发者应保持警惕。
延伸问答
升级 Nuxt 4 后 CSS 样式丢失的原因是什么？
CSS 样式丢失是因为 CSS Modules 的哈希在客户端和服务端生成时不一致。
如何解决 Nuxt 4 中 CSS 样式丢失的问题？
可以通过将 .module.less 文件改为 .module.css，或者在 nuxt.config.ts 中配置 generateScopedName 来解决问题。
为什么将文件后缀改为 .css 可以解决样式丢失问题？
因为 Vite 在处理 .css 文件时，哈希计算的一致性得以保持，避免了预处理器带来的路径不一致问题。
使用 generateScopedName 配置的作用是什么？
generateScopedName 配置可以确保在 SSR 和客户端构建中使用相同的规则生成类名，从而消除哈希不一致的问题。
在 Nuxt 4 中，哪些文件需要修改后缀名以解决问题？
所有的 .module.less 文件都需要改为 .module.css，以彻底修复样式丢失的问题。
为什么 Vite 在处理 CSS 预处理器时会出现哈希不一致的问题？
因为 Vite 对于 SSR 和客户端构建的中间产物处理方式不同，导致传给 CSS Modules 的路径不一致，从而产生不同的哈希。
