Android 接入 Google SDK 報錯：網路連接異常解決方案

問題現象

Android 專案接入 Google Play Services、Firebase、Maps SDK 等 Google 服務時，編譯或執行階段報錯，常見錯誤包括：Connection timed out、Unknown host 'maven.google.com'、Failed to resolve: com.google.gms:google-services 等。錯誤截圖顯示 Gradle 同步失敗、依賴下載超時。

根本原因

中國大陸網路環境無法直接訪問 Google Maven 倉庫（maven.google.com、dl.google.com）、Gradle 官方倉庫（services.gradle.org）及 JCenter（已停止服務）。導致依賴解析失敗、外掛程式下載超時、AAR 檔案無法獲取。

解決方案（按推薦順序）

方案一：配置國內鏡像源（最穩定、永久生效）

修改專案根目錄 build.gradle，將 repositories 替換為阿里雲、騰訊雲或華為雲鏡像：

buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        gradlePluginPortal()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.3.0'
        classpath 'com.google.gms:google-services:4.3.14'
    }
}

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        mavenCentral()
    }
}

同步修改 gradle/wrapper/gradle-wrapper.properties 的 distributionUrl 為國內鏡像：

distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-7.5-all.zip

方案二：使用 VPN/代理工具（臨時、不穩定）

在 Android Studio 中配置 HTTP Proxy（Settings → Appearance & Behavior → System Settings → HTTP Proxy），或在 gradle.properties 添加：

systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=7890
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=7890

缺點：代理不穩定易斷連、公司網路可能禁用、CI/CD 環境難配置。

方案三：離線下載依賴（適用於完全斷網環境）

1. 在可訪問 Google 的機器上執行 ./gradlew --offline dependencies 下載所有依賴到 ~/.gradle/caches
2. 將 caches/modules-2/files-2.1 目錄複製到目標機器對應位置
3. 在 gradle.properties 添加 offline=true

常見坑點與驗證

• Google Services 外掛程式版本：需與 Firebase/Play Services 版本相容，查看 官方版本對照表
• AndroidManifest 權限：確保已添加 INTERNET、ACCESS_NETWORK_STATE 權限
• 驗證方法：執行 ./gradlew --refresh-dependencies 強制重新解析，觀察 Console 輸出是否從鏡像源下載

總結

強烈建議採用方案一（配置國內鏡像源），一次配置永久生效，不依賴外部網路環境，適合團隊協作與 CI/CD 流水線。VPN 方案僅作應急，不可作為長期依賴。