TanStack Form 在 StrictMode 下嵌套值消失问题解析

问题现象

在使用 React 的 StrictMode 时，开发者发现 TanStack Form 的 pushValue 方法在处理数组字段时出现异常行为。具体表现为：当尝试向数组字段添加新值时，虽然底层状态似乎完成了添加操作，但界面显示会立即回滚到之前的状态。

问题复现

通过简化示例可以清晰地复现该问题：

1. 将应用包裹在 StrictMode 中
2. 将字段类型从对象数组改为字符串数组
3. 点击"添加"按钮时，新行不会显示

有趣的是，当数组元素为对象时，StrictMode 下表现正常；仅当数组元素为基本类型（如字符串）时才会出现问题。

根本原因分析

经过深入排查，发现问题源于 TanStack Form 内部的状态管理机制与 React StrictMode 的双重渲染特性的交互问题。具体流程如下：

1. 首次渲染（StrictMode 的虚拟渲染）：

   • 初始化 people[0] 的 FieldAPI，将其添加到 FormAPI.state.values 数组
   • 执行清理操作，删除 people[0]

2. 实际渲染：

   • 再次创建 people[0]，但由于 defaultValue 未定义，未触发表单通知
   • 处理 people 字段，重新创建空数组

这种执行顺序导致最终数组为空，新添加的值无法保留。

解决方案

临时解决方案是为字段指定默认值：

<form.Field key={i} defaultValue={""} name={`people[${i}]`}/>

长期来看，TanStack Form 需要改进其通知机制，建立优先级系统和自底向上的通知树，确保字段状态变更的顺序正确性。

相关现象

开发者还报告了以下相关现象：

1. 控制台会出现 React 警告，提示在渲染过程中更新组件
2. 对于嵌套对象数组，仍存在部分字段丢失的问题
3. removeValue 和 swapValues 方法也可能出现类似问题

最佳实践建议

1. 始终为数组字段元素指定 defaultValue
2. 在 StrictMode 下进行充分测试
3. 关注控制台警告，但可以暂时忽略特定的状态更新警告
4. 对于复杂嵌套结构，考虑使用 preserveValue 属性

这个问题展示了现代前端框架中状态管理库与 React 严格模式交互时的典型挑战，理解其底层机制有助于开发者更好地诊断和解决类似问题。