通过通道同步PouchDB与CouchBase（Sync Gateway）-本地文档404错误

我之前在做PouchDB和Couchbase Sync Gateway同步的时候也碰到过一模一样的问题，先给你吃个定心丸：这个404很多时候只是同步流程里的“小插曲”，不一定会影响实际的文档同步，咱们一步步来排查解决：

先搞懂错误的本质 #

你看到的这个GET http://localhost:4984/db/_local/nKlC5IrimnHOiQZcwE_LYA%3D%3D 404 (Not Found)错误，是PouchDB在同步过程中，尝试从Sync Gateway获取同步检查点（checkpoint）文档导致的。这类_local前缀的文档是PouchDB用来记录同步进度的标记，第一次同步或者Sync Gateway上还没有对应的checkpoint时，就会抛出这个404。

具体解决步骤 #

1. 检查Sync Gateway的同步函数配置 #

Sync Gateway对_local文档的处理需要明确授权，你得确保同步函数里允许这类文档的读写。打开你的Sync Gateway配置文件（比如sync-gateway-config.json），在数据库的sync函数里加上这段逻辑：

function(doc, oldDoc) {
  // 允许同步_local开头的检查点文档
  if (doc._id.startsWith("_local/")) {
    return true;
  }
  // 下面是你原本的同步逻辑
  // ...
}

修改后重启Sync Gateway，让配置生效。

2. 验证同步是否真的异常 #

很多时候这个404只是PouchDB在尝试获取不存在的checkpoint，后续会自动创建新的checkpoint文档，不会影响实际的文档同步。你可以做个测试：

• 在本地PouchDB新增一个文档，看是否能同步到Sync Gateway（可以通过Sync Gateway的管理界面或者Couchbase Server查看）
• 反过来在Couchbase Server里新增文档，看是否能同步到浏览器的IndexedDB

如果双向同步都正常，那这个404完全可以忽略，或者你可以在PouchDB的同步错误回调里过滤掉这类错误：

localDb.sync(remoteDb, { live: true, retry: true })
  .on('error', function(err) {
    // 过滤_local文档的404错误
    if (err.status === 404 && err.url.includes('_local/')) {
      return;
    }
    // 处理其他真正的同步错误
    console.error('同步异常:', err);
  });

3. 重置同步状态（如果同步确实异常） #

如果发现文档同步不正常，那就试试重置整个同步状态：

• 在浏览器的开发者工具里，找到Application标签，清除对应的IndexedDB数据库（也就是你的本地PouchDB）
• 重启Sync Gateway服务
• 重新初始化PouchDB的同步逻辑，让它从头开始创建新的checkpoint文档

这样基本就能解决大部分_local文档的404问题了。

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