Couchbase Lite 1.5升级2.0后持续复制同步异常求助

我之前帮不少开发者踩过Couchbase Lite 2.0的复制器坑，你遇到的这个“仅应用启动时拉取变更，后续不再同步”的问题，核心原因几乎都是复制器实例被垃圾回收（GC）回收了——这是2.0版本和1.5版本最大的差异之一：1.5里框架会帮你维护复制器的引用，但2.0完全需要开发者自己管理。

下面是具体的排查和解决步骤：

1. 必须保留复制器的全局强引用 #

这是最常见的问题：如果你的复制器是在StartSync方法里创建的局部变量，方法执行完毕后这个变量就会被标记为可回收，GC触发后复制器就会停止工作，自然没法持续同步。

解决方法是在你的类级别声明一个全局变量来持有复制器实例：

// 类级别的全局变量，防止被GC回收
private Replicator _replicator;

然后在StartSync方法里给这个全局变量赋值，而不是用局部变量。

2. 检查复制器配置与启动逻辑 #

确保你的复制器配置正确设置了推拉模式，并且正确启动了复制器：

public void StartSync(Uri syncEndpoint, string username, ISecureString password)
{
    if (_database == null)
    {
        throw new DataHandlerException(DataHandlerError.DatabaseDoesntExist);
    }

    var endpoint = new URLEndpoint(syncEndpoint);
    // 配置复制器为推拉模式
    var config = new ReplicatorConfiguration(_database, endpoint)
    {
        ReplicatorType = ReplicatorType.PushAndPull,
        // 正确配置身份认证
        Authenticator = new PasswordAuthenticator(username, ConvertToUnsecureString(password))
    };

    // 给全局变量赋值，保留引用
    _replicator = new Replicator(config);

    // 启动复制器
    _replicator.Start();
}

// 辅助方法：将ISecureString转换为普通字符串（注意安全场景下的内存清理）
private string ConvertToUnsecureString(ISecureString securePassword)
{
    if (securePassword == null)
        return string.Empty;

    IntPtr unmanagedString = IntPtr.Zero;
    try
    {
        unmanagedString = Marshal.SecureStringToGlobalAllocUnicode(securePassword);
        return Marshal.PtrToStringUni(unmanagedString);
    }
    finally
    {
        Marshal.ZeroFreeGlobalAllocUnicode(unmanagedString);
    }
}

3. 添加状态监听，排查同步异常 #

建议给复制器添加Changed事件监听，这样可以实时查看复制器的状态，比如是否因为网络断开、认证失败而停止：

_replicator.Changed += (sender, e) =>
{
    switch (e.Status.Activity)
    {
        case ReplicatorActivityLevel.Connecting:
            Console.WriteLine("正在连接同步网关...");
            break;
        case ReplicatorActivityLevel.Replicating:
            Console.WriteLine($"已同步 {e.Status.CompletedChanges} / {e.Status.TotalChanges} 条变更");
            break;
        case ReplicatorActivityLevel.Stopped:
            if (e.Status.Error != null)
            {
                Console.WriteLine($"复制器意外停止：{e.Status.Error.Message}");
                // 这里可以添加重试逻辑，比如延迟几秒后重新启动
            }
            break;
        case ReplicatorActivityLevel.Offline:
            Console.WriteLine("网络离线，等待恢复...");
            break;
    }
};

额外注意事项 #

• 移动端应用进入后台时，部分平台会限制网络访问，复制器会进入Offline状态，恢复网络后通常会自动重试，如果没有自动重试，可以在Offline状态触发时添加手动重试逻辑。
• 确保同步网关的配置允许持续复制，没有设置过短的超时时间，或者限制了连接时长。

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