React Router v7 中 ErrorBoundary 的 Hydration 问题解析

问题背景

在 React Router v7 版本中，开发者在使用 ErrorBoundary 组件时遇到了一个常见的 Hydration 错误。这个错误表现为当在 ErrorBoundary 中包含 <Scripts /> 或 <Links /> 组件时，控制台会显示警告信息："Expected server HTML to contain a matching in "。

问题现象

具体表现为两种场景：

1. 当在 ErrorBoundary 中直接包含 <Scripts /> 组件时，会出现 Hydration 不匹配的错误
2. 即使将相关组件移到 Layout 中，仍然会出现类似问题，特别是 <Links /> 组件在服务器端和客户端生成的 HTML 标签格式不一致（服务器端生成自闭合标签 <link ... />，而客户端生成非自闭合标签 <link ... >）

技术分析

Hydration 机制

React 的 Hydration 是指将服务器端渲染的静态 HTML 与客户端的 React 应用进行"水合"的过程。在这个过程中，React 会检查服务器端生成的 DOM 结构与客户端渲染的虚拟 DOM 是否完全匹配。如果发现不一致，就会抛出 Hydration 错误。

ErrorBoundary 的特殊性

ErrorBoundary 在 React Router 中用于捕获和显示路由级别的错误。与常规组件不同，ErrorBoundary 在渲染时需要考虑完整的 HTML 结构，因为它可能在应用初始化阶段就触发。

问题根源

1. 冗余组件问题：在 ErrorBoundary 中直接包含 <Scripts /> 是多余的，因为根 Layout 组件已经提供了这些内容
2. 标签格式不一致：React Router 的 <Links /> 组件在服务器端和客户端生成的 HTML 标签格式存在差异，导致 Hydration 失败

解决方案

推荐方案

1. 避免在 ErrorBoundary 中重复包含资源组件：依赖根 Layout 提供的 <Scripts /> 和 <Links /> 即可
2. 检查第三方库的兼容性：如使用 Mantine 等 UI 库时，确保其与 React Router v7 的兼容性

临时解决方案

对于必须包含资源组件的情况，可以考虑以下方法：

1. 升级 React 版本：有开发者报告使用 React 19 可以解决此问题
2. 调整未来标志：禁用 v3_lazyRouteDiscovery 标志（虽然这会牺牲一些性能优化）

最佳实践

1. 保持 ErrorBoundary 简洁：仅包含必要的错误展示内容
2. 统一资源管理：将所有资源引用集中在根 Layout 中
3. 渐进式升级：从 React Router v2 升级到 v7 时，逐步验证各功能模块

总结

React Router v7 中的 ErrorBoundary Hydration 问题主要源于组件冗余和标签生成不一致。通过理解 React 的 Hydration 机制和 ErrorBoundary 的特殊性，开发者可以采取适当的解决方案。建议遵循框架的最佳实践，保持组件结构的简洁和一致性，以确保应用的稳定运行。