Firebase Firestore在设备连接Wi-Fi/移动数据但无实际互联网时未触发失败回调的问题

我之前开发Firebase相关应用时也碰到过完全一样的场景，这其实是Firestore默认的离线优先设计导致的，给你拆解一下原因和具体的解决办法：

为什么会出现这个问题？ #

Firestore的核心设计是离线优先——当系统检测到设备“已连接网络”（比如Wi-Fi或移动数据已连上），它会默认把写操作缓存到本地设备，然后持续尝试和Firebase服务器建立连接，这个过程中不会立刻返回失败回调，而是会一直等待直到重试超时或者网络恢复。而你遇到的“有Wi-Fi/移动数据但无实际互联网”的场景，系统的网络状态API会返回“已连接”，所以Firestore直接进入了缓存重试流程，不会触发你期望的即时失败回调。

具体解决办法 #

1. 执行Firestore操作前，先做实际连通性校验

不要只依赖系统的网络状态判断（比如Android的ConnectivityManager、iOS的NWPathMonitor），这些只能判断设备是否连了网络硬件，没法确认能不能通到Firebase服务器。你可以发起一个极轻量的HTTP HEAD请求到Firestore的服务域名，设置短超时（比如3秒），先确认实际能连通再执行写操作：

举个Android Kotlin的示例：

// 校验Firebase服务是否可达
suspend fun isFirestoreReachable(): Boolean {
    return try {
        val client = OkHttpClient.Builder()
            .connectTimeout(3, TimeUnit.SECONDS)
            .callTimeout(3, TimeUnit.SECONDS)
            .build()
        val request = Request.Builder()
            .url("https://firestore.googleapis.com/")
            .head() // HEAD请求比GET更轻量，只返回响应头
            .build()
        val response = client.newCall(request).execute()
        response.isSuccessful
    } catch (e: Exception) {
        // 抛出异常说明连不上
        false
    }
}

// 实际调用逻辑
if (isFirestoreReachable()) {
    // 确认能连通，再执行Firestore写操作
    firestore.collection("rent_collections").add(rentData)
        .addOnSuccessListener {
            // 你的现有成功回调逻辑
        }
        .addOnFailureListener {
            // 处理Firestore自身的业务错误（比如权限不足、数据格式问题）
        }
} else {
    // 触发你需要的「无实际互联网」失败回调
    showNoInternetError()
}

2. 调整Firestore的连接超时设置

如果你不想提前做连通性校验，也可以通过Firestore的配置缩短连接超时时间，让它更快放弃重试并返回失败。比如Android端的配置：

val firestoreSettings = FirebaseFirestoreSettings.Builder()
    .setPersistenceEnabled(true) // 如果你需要保留离线持久化功能的话
    .setConnectTimeout(5, TimeUnit.SECONDS) // 缩短连接超时
    .setReadTimeout(5, TimeUnit.SECONDS)
    .build()
FirebaseFirestore.getInstance().firestoreSettings = firestoreSettings

不过要注意：这个超时是单次连接的超时，Firestore仍然会在一段时间内重试，所以这个方法只能加速失败回调的触发，没法完全替代实际连通性校验。

3. 监听Firestore的实际连接状态

Firebase提供了专门的监听器，可以直接获取Firestore和服务器的实际连接状态，而不是系统的网络状态。你可以在应用启动时注册这个监听器，实时感知连接状态：

Android示例：

val firestore = FirebaseFirestore.getInstance()
firestore.addNetworkStateListener { isConnected ->
    // isConnected为true时，Firestore确实能和服务器通信
    // 为false时，不管系统显示什么网络状态，Firestore都连不上服务器
    if (!isConnected) {
        // 可以在这里全局处理无实际互联网的情况
    }
}

你可以在执行写操作前，先检查这个监听器返回的状态，再决定是否执行操作或触发失败回调。

总结 #

优先推荐第一种「提前做连通性校验」的方案，它最直接可靠；第二种调整超时可以作为辅助；第三种监听器适合全局感知网络状态的场景。根据你的业务需求选就行！

内容来源于stack exchange