Angular Material 中 MatSidenav 内 MatTooltip 的水合错误解析

问题概述

在 Angular Material 项目中，当开发者尝试在 MatSidenav 组件内部使用 MatTooltip 指令时，如果启用了 SSR（服务器端渲染）和水合（Hydration）功能，会在鼠标悬停时触发一个严重的运行时错误。这个错误表现为控制台抛出"Unexpected state: no hydration info available for a given TNode"的断言错误，导致工具提示功能完全失效。

技术背景

Angular 的水合机制是 SSR 中的关键环节，它负责将服务器渲染的静态内容与客户端 Angular 应用"融合"起来，保持 DOM 结构的一致性同时添加交互能力。MatTooltip 作为 Angular Material 的动态组件，会在运行时创建额外的视图容器来承载工具提示内容。

错误原因分析

问题的根本原因在于水合过程中视图容器的处理逻辑存在缺陷。具体表现为：

1. 当 MatTooltip 被放置在 MatSidenav 内部时，Angular 的水合系统无法正确追踪到工具提示组件对应的视图容器节点
2. 水合系统在尝试定位或创建锚点节点时，发现缺少必要的 hydration 信息
3. 系统无法为工具提示的视图容器建立正确的引用关系

影响范围

该问题主要影响以下技术组合：

• 使用 Angular 19.x 版本
• 启用了 SSR 和客户端水合功能（特别是 withEventReplay）
• 在 MatSidenav 内部使用 MatTooltip
• 开发环境或生产环境都会出现

解决方案

Angular 团队已经确认并修复了此问题。开发者可以通过以下方式解决：

1. 升级到包含修复的 Angular Material 版本（修复提交在相关 PR 中）
2. 临时解决方案是避免在 MatSidenav 内部使用 MatTooltip
3. 或者暂时禁用水合功能中的事件回放特性

技术启示

这个问题揭示了 SSR 架构中几个重要技术点：

1. 动态组件与水合机制的兼容性挑战
2. 视图容器在服务端和客户端渲染中的一致性维护
3. 复杂组件嵌套场景下的 hydration 信息传递

最佳实践建议

对于开发者在类似场景下的工作，建议：

1. 对 SSR 应用中的动态组件进行充分测试
2. 关注组件嵌套层次对水合过程的影响
3. 保持框架和库的及时更新
4. 复杂交互组件考虑添加水合状态检查

总结

这个案例展示了现代前端框架中 SSR 实现的复杂性，特别是当动态内容与静态水合机制交互时可能产生的边界情况。Angular 团队通过框架层面的修复解决了此问题，同时也提醒开发者在架构设计时需要充分考虑渲染模式差异带来的潜在问题。