Waku项目中CSS模块在开发模式下的类名同步问题分析

问题现象

在Waku项目的开发模式下，当使用CSS模块配合客户端组件时，会出现样式类名不同步的问题。具体表现为：

1. 首次加载页面时样式显示正常
2. 修改样式后热更新也能正常工作
3. 但刷新页面后，元素的类名会回退到之前的版本
4. 再次修改样式文件后，显示又恢复正常，直到下一次刷新

这个问题仅出现在开发模式，生产构建不受影响。值得注意的是，服务端组件(RSC)完全不受此问题影响，只有客户端组件及其内部组件会出现类名不同步的情况。

问题复现步骤

1. 创建一个新的Waku项目
2. 添加一个客户端组件和对应的CSS模块文件
3. 为某个元素添加明显的样式（如带颜色的div）
4. 启动开发服务器并访问页面
5. 修改元素样式，确认热更新正常工作
6. 刷新页面，发现类名不同步
7. 再次修改样式，显示恢复正常，但刷新后问题重现

技术分析

这个问题本质上与Vite的热更新机制有关。在开发模式下：

1. 初始加载时，CSS模块会生成唯一的类名映射
2. 热更新时，Vite会正确地更新这些映射关系
3. 但页面刷新后，客户端组件似乎缓存了之前的类名映射
4. 服务端组件不受影响，因为它们在每次请求时都会重新生成

这种不一致性表明，Waku在开发模式下对CSS模块的处理可能存在以下问题：

• 客户端组件的CSS模块类名没有正确参与热更新链
• 刷新时类名映射的持久化机制存在缺陷
• 服务端和客户端在CSS模块处理上存在不一致

临时解决方案

目前发现的临时解决方案包括：

1. 重启开发服务器 - 可以完全重置状态
2. 修改样式文件 - 可以临时恢复正确显示
3. 使用服务端组件替代客户端组件 - 完全避免此问题

深入探讨

这个问题与前端构建工具处理CSS模块的方式密切相关。在理想情况下：

1. 模块化的CSS应该保证类名的唯一性和一致性
2. 热更新应该保持类名映射的同步
3. 刷新操作不应该破坏这种同步关系

Waku作为基于RSC的框架，可能在处理客户端组件的CSS模块时，没有完全考虑到开发模式下频繁的模块更新和刷新场景。这提示我们在使用CSS模块时需要注意：

• 开发模式和生产模式可能存在差异
• 客户端组件可能带来额外的复杂性
• 样式更新链需要完整的测试验证

总结

Waku项目中的这个CSS模块类名同步问题，揭示了前端开发中一个常见但容易被忽视的场景 - 开发模式下资源更新的完整性。虽然生产环境不受影响，但开发体验的流畅性同样重要。这个问题的解决将有助于提升Waku框架的开发体验和稳定性。