SolidJS 中的 Hydration 不匹配问题解析

问题现象

在 SolidJS 项目中，开发者可能会遇到一个特殊的 Hydration 不匹配错误，错误信息显示"Unable to find DOM nodes for hydration key"。这个错误会导致热重载停止工作，页面上的所有交互功能也会失效。

问题本质

这个问题的核心在于 SolidJS 的响应式系统和 SSR(服务器端渲染)的 Hydration 机制之间的配合问题。当组件在服务器端渲染时生成的 DOM 结构与客户端 Hydration 时预期的结构不一致时，就会出现这种错误。

具体案例分析

在示例代码中，开发者尝试将一个包含 JSX 元素的对象数组作为 props 传递给子组件。问题出现在以下几个方面：

1. 直接传递 JSX 元素：在 props 中直接存储 JSX 元素会导致每次访问时都重新创建新的 DOM 节点
2. 嵌套元素问题：当 JSX 中包含嵌套元素(如<b>标签)时，问题更容易显现
3. createMemo 的影响：使用 createMemo 会缓存计算结果，但可能加剧 Hydration 不匹配

解决方案

方案一：使用函数返回 JSX

将 props 中的 value 改为函数形式，确保 JSX 是惰性求值的：

interface TextTableProps {
  items: {
    name: string;
    value: () => JSX.Element;  // 改为函数形式
  }[];
}

使用时调用函数：

<div>
  {item.name}: {item.value()}  // 调用函数获取 JSX
</div>

方案二：使用 children 辅助函数

SolidJS 提供了 children 辅助函数来处理这种情况：

const propItems = children(() => props.items).toArray();
const maxNameLength = createMemo(() =>
  Math.max(...propItems.map((item) => item.name.length))
);

const items = () =>
  propItems.map((item) => (
    <div>
      {item.name}: {item.value}
    </div>
  ));

这种方法可以确保在多个地方使用 props 时不会重复创建 DOM 节点。

技术原理

SolidJS 的响应式系统采用惰性求值策略，这意味着表达式只有在真正需要时才会被计算。在 SSR 场景下：

1. 服务器端会预先计算并渲染出完整的 HTML
2. 客户端进行 Hydration 时，会尝试匹配服务器端生成的 DOM 结构
3. 如果在客户端重新创建了 DOM 节点(而不是复用服务器端的)，就会导致 Hydration 失败

最佳实践建议

1. 避免在 props 中直接存储 JSX 元素
2. 对于需要传递的 UI 片段，优先使用函数形式或 children 模式
3. 在 SSR 应用中特别注意响应式数据的处理方式
4. 简化嵌套结构可以减少 Hydration 问题的发生概率

总结

SolidJS 的这种设计实际上是为了提高性能而做出的权衡。理解 SolidJS 的响应式原理和 Hydration 机制，可以帮助开发者避免这类问题，写出更健壮的 SSR 应用。当遇到类似问题时，考虑将 JSX 创建延迟到真正需要时，或者使用框架提供的工具函数来处理，通常都能找到解决方案。