离线场景下Firebase RTDB新节点keepSynced()生效机制问题

keepSynced(true) 不需要在调用时刻保持和Firebase后端的连接，但对应节点的离线缓存、离线监听即时生效的前提，是该节点至少完成过一次与服务端的成功初始同步。你观测到的现象完全符合SDK设计逻辑，不是bug。

底层运行逻辑 #

• keepSynced() 的本质是SDK为目标节点自动挂载一个低优先级的隐式内部监听器，仅实现两个固定能力：
  • 网络连通时自动拉取目标节点的全量数据，同步到本地持久化缓存
  • 给目标节点的缓存打常驻标记，不会被SDK的自动缓存清理策略回收
• 完全离线状态下，如果目标节点从未和服务端完成过同步，此时调用keepSynced(true)只会在本地记录「该节点需要常驻缓存」的配置，不会凭空初始化该节点的本地缓存索引。离线状态下SDK无法确认目标节点在服务端的存在状态、数据结构，不会创建不完整的本地缓存根节点。
• 你提供的离线复现代码，SDK的完整执行链路如下：

// Execute this while offline:

// Enable permanent offline sync for a new node that doesn't exist yet on the Firebase server
await database.ref().child('new_node').keepSynced(true);

// Register listener
database.ref().child('new_node').onValue.listen((event) => print(event));

// Add data
database.ref().child('new_node/child').set({'key': 'value'});

1. 第一步调用keepSynced(true)时，SDK仅记录new_node的常驻缓存标记，不初始化本地缓存
2. 第二步注册onValue监听器时，SDK检测到该节点未完成初始同步，不会立刻触发回调，会等待初始同步完成后再派发事件
3. 第三步调用set()写入数据时，写入操作会被存入本地待同步队列，但因为节点未完成初始同步，SDK不会将这次本地变更派发给业务层监听器，避免返回不完整的脏数据
4. 设备恢复联网后，SDK首先通过隐式内部监听器拉取new_node的服务端数据（此时服务端无该节点，返回空值），完成初始同步流程、建立本地缓存索引；随后将待同步队列里的set()请求推送给服务端，同步更新本地缓存，此时才会触发注册的监听器回调

• 一旦节点完成过一次初始同步，后续无论在线还是离线场景，keepSynced()的缓存保活、监听器事件即时派发、本地写入触发回调的逻辑都会正常运行，和观测到的「首次联网后全场景正常」的现象完全匹配。

关于官方文档的说明 #

官方文档对keepSynced()的描述如下：

对某一数据位置调用keepSynced(true)后，即使该位置未挂载任何监听器，对应位置的数据也会被自动下载并保持同步；此外，被设置为保持同步状态的位置数据不会被从持久化磁盘缓存中清除。

文档中提到的「自动下载」指的是SDK在网络可用时自动执行的拉取同步动作，不要求调用keepSynced()的当下必须处于联网状态，SDK会在下次网络恢复时自动补做拉取动作；但在初始同步完成前，该节点的离线事件即时派发能力不会启用。

实操参考 #

如果业务需要支持离线创建全新节点、且注册的监听器需要立刻收到本地写入的回调，可以在应用首次安装后第一次联网启动时，提前给所有业务会用到的节点根路径调用一次keepSynced(true)，完成初始同步标记，后续离线操作就不会出现等待联网才触发回调的问题。

内容的提问来源于stack exchange，提问作者jbxbergdev