React Router 中懒加载路由清单的缓存问题解析

在 React Router 7.3.0 版本中，开发者们发现了一个关于懒加载路由清单缓存的潜在问题。这个问题主要影响使用 CDN（如 CloudFront）部署的应用，可能导致客户端在应用更新后仍然获取到旧版本的路由信息。

问题背景

React Router 的懒加载路由发现机制会生成一个特殊的清单文件（manifest），其中包含了应用的所有路由信息。这个清单文件通过 HTTP 请求获取，默认设置了非常长的缓存时间（31536000 秒，约1年），并且标记为不可变（immutable）。

问题表现

当应用部署新版本后，可能会出现以下两种异常情况：

1. 客户端导航失效：由于 CDN 缓存了旧版本的清单文件，客户端可能无法获取到新增或修改的路由信息，导致导航到某些页面时出现404错误，但刷新页面后又恢复正常。

2. 版本检测失效：React Router 7.3.0 引入了版本检测机制，用于在服务器和客户端版本不匹配时触发页面刷新。但由于缓存的存在，客户端可能永远无法检测到版本不匹配的情况。

技术原理

问题的核心在于 HTTP 缓存控制头部的设置。React Router 服务器运行时默认给清单响应添加了以下缓存头：

Cache-Control: public, max-age=31536000, immutable

这种设置虽然考虑了性能优化，但忽略了应用更新时的版本一致性需求。特别是当使用 CDN 时，这种强缓存策略会导致清单文件被长期缓存。

解决方案

对于这个问题，开发者社区提出了几种解决方案：

1. 配置 CDN 忽略清单文件缓存：在 CDN 配置中，可以针对 /__manifest* 路径的请求禁用缓存。

2. 利用版本参数作为缓存破坏者：清单请求中包含版本参数（如 version=1），理论上每次版本更新都会改变这个参数，从而绕过缓存。但实际部署中可能因 CDN 配置而失效。

3. 主动版本检测：可以设置一个专门的路由来返回当前部署版本，客户端定期轮询这个接口，在检测到新版本时主动触发页面刷新。

最佳实践建议

对于生产环境部署，建议采取以下措施：

1. 评估 CDN 的查询字符串缓存策略，确保版本参数能够有效破坏缓存
2. 考虑缩短清单文件的缓存时间，或在部署后主动清除 CDN 缓存
3. 实现客户端版本检测机制，确保用户能够及时获取应用更新
4. 在开发环境中监控清单请求，确认缓存行为符合预期

React Router 团队也在持续优化这一机制，未来版本可能会提供更灵活的缓存控制选项，帮助开发者更好地平衡性能与更新一致性。