前言

在使用 Gradle 進行 Java、Android 或其他 JVM 項目開發(fā)時，最令人頭疼的問題之一就是依賴下載速度慢。由于 Gradle 默認的中央倉庫（如 Maven Central、JCenter 等）位于國外，網(wǎng)絡連接不穩(wěn)定或延遲高，常常導致構建過程耗時過長，甚至失敗。

解決方案：配置國內(nèi)鏡像源，將依賴下載請求重定向到國內(nèi)的鏡像服務器，顯著提升下載速度，縮短構建時間。

本文將為你提供最詳細、最全面的 Gradle 配置國內(nèi)鏡像的指南，涵蓋多種配置方式、不同場景、常見問題及最佳實踐，助你徹底解決依賴下載慢的痛點。

一、為什么需要配置國內(nèi)鏡像

1. 地理位置優(yōu)勢：國內(nèi)鏡像服務器（如阿里云、華為云、騰訊云等）位于中國境內(nèi)，網(wǎng)絡延遲低，訪問速度快。
2. 網(wǎng)絡穩(wěn)定性：避免了跨國網(wǎng)絡波動、丟包等問題，下載過程更穩(wěn)定。
3. 提升開發(fā)效率：減少等待時間，加快項目構建、編譯和測試速度。
4. 避免構建失敗：網(wǎng)絡超時或連接中斷導致的依賴下載失敗問題大大減少。

二、主流的 Gradle 國內(nèi)鏡像源

以下是國內(nèi)廣泛使用且穩(wěn)定的鏡像源：

推薦：阿里云鏡像，因其速度快、覆蓋全、穩(wěn)定性高，是目前最受歡迎的選擇。

三、配置 Gradle 國內(nèi)鏡像的四種方法

Gradle 提供了多種配置鏡像源的方式，你可以根據(jù)項目需求和團隊規(guī)范選擇最適合的一種。

方法一：全局配置（推薦用于個人開發(fā)）

適用于所有 Gradle 項目，只需配置一次，永久生效。

步驟：

1.找到或創(chuàng)建 Gradle 的用戶主目錄配置文件。

• Windows: C:\Users\<你的用戶名>\.gradle\init.gradle
• macOS/Linux: ~/.gradle/init.gradle
• 如果.gradle目錄或init.gradle文件不存在，請手動創(chuàng)建。

2.在init.gradle文件中添加以下內(nèi)容：

// init.gradle - 全局配置鏡像源
initscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        mavenCentral()
    }
}

// 為所有項目配置倉庫
allprojects {
    repositories {
        // 移除默認的jcenter()和mavenCentral()
        // 添加阿里云鏡像
        maven { url 'https://maven.aliyun.com/repository/public' }
        // 也可以添加其他國內(nèi)鏡像作為備選
        // maven { url 'https://repo.huaweicloud.com/repository/maven/' }
        // maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }

        // 如果項目需要，可以保留對Google等特定倉庫的引用
        // google()
        // gradlePluginPortal()
    }

    // 配置依賴解析規(guī)則（可選，用于重定向）
    configurations.all {
        resolutionStrategy {
            // 強制使用鏡像源（可選，更徹底）
            dependencySubstitution {
                // 例如：將jcenter的請求重定向到阿里云
                // substitute module('jcenter') using module('maven:https://maven.aliyun.com/repository/public')
            }
        }
    }
}

優(yōu)點：

• 一勞永逸，所有項目自動生效。
• 無需修改每個項目的build.gradle文件。

缺點：

• 如果團隊協(xié)作，其他成員也需要單獨配置。
• 可能影響某些需要訪問原始倉庫的特殊項目。

方法二：項目級配置（推薦用于團隊協(xié)作）

適用于單個項目，配置寫在項目文件中，團隊成員克隆項目后自動生效。

步驟：

• 打開項目的build.gradle文件（通常是根項目的build.gradle）。
• 找到repositories塊，注釋或刪除原有的jcenter()和mavenCentral()。
• 添加國內(nèi)鏡像源。

// build.gradle (Project Level)
buildscript {
    repositories {
        // 原有配置（可選）
        // jcenter()
        // mavenCentral()

        // 使用阿里云鏡像
        maven { url 'https://maven.aliyun.com/repository/public' }
        // 或使用華為云
        // maven { url 'https://repo.huaweicloud.com/repository/maven/' }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.0.2' // 示例
        // 其他classpath依賴
    }
}

allprojects {
    repositories {
        // 原有配置（可選）
        // jcenter()
        // mavenCentral()
        // google()
        // gradlePluginPortal()

        // 優(yōu)先使用國內(nèi)鏡像
        maven { url 'https://maven.aliyun.com/repository/public' }
        // 可以添加多個鏡像源，Gradle會按順序嘗試
        maven { url 'https://repo.huaweicloud.com/repository/maven/' }
        maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }

        // 保留必要的官方倉庫
        google() // Android項目需要
        gradlePluginPortal() // Gradle插件需要
    }
}

// 清理未使用的倉庫（可選）
task clean(type: Delete) {
    delete rootProject.buildDir
}

優(yōu)點：

• 配置隨項目版本控制，團隊成員共享。
• 不影響其他項目的構建環(huán)境。

缺點：

每個項目都需要單獨配置。

方法三：通過settings.gradle配置（Gradle 5.0+ 推薦）

Gradle 5.0 引入了settings.gradle中的dependencyResolutionManagement，是官方推薦的集中管理依賴和倉庫的方式。

步驟：

在項目根目錄的settings.gradle文件中添加：

// settings.gradle
rootProject.name = 'YourProjectName'

// 配置依賴解析管理（Gradle 5.0+）
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        // 清除默認倉庫
        // mavenCentral()
        // jcenter()

        // 添加國內(nèi)鏡像
        maven {
            name = "Aliyun Maven"
            url = uri("https://maven.aliyun.com/repository/public")
            // 可選：配置認證（如果鏡像需要）
            // credentials {
            //     username = 'your-username'
            //     password = 'your-password'
            // }
        }

        maven {
            name = "Huawei Maven"
            url = uri("https://repo.huaweicloud.com/repository/maven/")
        }

        // 保留必要的官方倉庫
        google()
        mavenCentral() // 如果鏡像不完整，可作為備選
        gradlePluginPortal()
    }
}

// 包含子項目（如果有）
include 'app'
// include 'library'

在build.gradle中不再需要重復定義repositories，除非有特殊需求。

優(yōu)點：

• 官方推薦，結構清晰，易于維護。
• 集中管理所有模塊的倉庫配置。
• 支持更復雜的依賴解析策略。

缺點：

僅適用于 Gradle 5.0 及以上版本。

方法四：通過gradle.properties配置代理（備選方案）

如果鏡像配置無效，或需要更底層的網(wǎng)絡控制，可以通過設置 HTTP 代理。

步驟：

在gradle.properties文件中（項目級或用戶級）添加：

# gradle.properties
# 設置HTTP代理（如果公司或網(wǎng)絡需要）
# org.gradle.jvmargs=-Dhttp.proxyHost=proxy.company.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.company.com -Dhttps.proxyPort=8080

# 或者直接設置倉庫URL（不推薦，不如方法三靈活）
# systemProp.maven.repo.remote=https://maven.aliyun.com/repository/public

注意：此方法主要用于代理，直接設置倉庫 URL 的效果有限，建議優(yōu)先使用前三種方法。

四、驗證配置是否生效

配置完成后，如何確認鏡像源已成功使用？

方法 1：查看構建日志

運行./gradlew build --info，在輸出日志中搜索Downloading或Download，觀察依賴的下載 URL 是否指向你配置的國內(nèi)鏡像地址。

方法 2：檢查網(wǎng)絡請求

使用網(wǎng)絡監(jiān)控工具（如 Wireshark、Fiddler）或瀏覽器開發(fā)者工具，觀察 Gradle 構建時的 HTTP 請求目標地址。

方法 3：對比構建時間

配置前后執(zhí)行./gradlew clean build，比較構建耗時，國內(nèi)鏡像通常能將時間從幾分鐘縮短到幾秒或幾十秒。

五、常見問題與解決方案

問題 1：配置后仍然從國外倉庫下載

• 檢查repositories順序：Gradle 按repositories列表的順序查找依賴，確保國內(nèi)鏡像排在mavenCentral()或jcenter()之前。
• 檢查settings.gradle：如果使用了dependencyResolutionManagement，確保repositoriesMode設置正確，且未在子項目中覆蓋。
• 清除 Gradle 緩存：運行./gradlew --stop停止守護進程，然后刪除~/.gradle/caches/目錄（謹慎操作），重新構建。

問題 2：某些依賴在鏡像中找不到

鏡像同步延遲：國內(nèi)鏡像可能有同步延遲，稍等一段時間再試。

依賴源特殊：某些私有庫或非主流倉庫不在鏡像范圍內(nèi)。解決方案：

• 在repositories中同時保留國內(nèi)鏡像和原始倉庫（如mavenCentral()）。
• 將國內(nèi)鏡像放在前面，Gradle 會優(yōu)先從鏡像下載，找不到時再嘗試原始倉庫。

問題 3：Android 項目提示“Failed to resolve: androidx.xxx”

確保在repositories中保留了google()倉庫，AndroidX 依賴必須從 Google 倉庫下載。

配置示例：

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

問題 4：Gradle 版本過低，不支持settings.gradle配置？

升級 Gradle 版本：修改gradle/wrapper/gradle-wrapper.properties中的distributionUrl。

distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip

使用build.gradle項目級配置。

六、最佳實踐與建議

優(yōu)先使用settings.gradle配置：對于 Gradle 5.0+項目，這是最現(xiàn)代和推薦的方式。

個人開發(fā)用全局配置：省時省力，一次配置，終身受益。

團隊項目用項目級配置：確保環(huán)境一致性，避免“在我機器上能跑”的問題。

組合使用多個鏡像：配置阿里云為主，華為云或騰訊云為備，提高可用性。

保留必要的官方倉庫：如google()、gradlePluginPortal()，避免功能缺失。

定期檢查鏡像狀態(tài)：關注鏡像源的官方公告，了解同步狀態(tài)和維護計劃。

文檔化配置：在項目 README 中說明倉庫配置，方便新成員加入。

七、總結

配置 Gradle 國內(nèi)鏡像是提升 JVM 項目開發(fā)效率的必備技能。通過本文介紹的四種方法，你可以靈活選擇最適合你場景的方案。

核心要點：

• 阿里云鏡像是首選。
• settings.gradle 是未來趨勢。
• 項目級配置利于團隊協(xié)作。
• 全局配置適合個人使用。

立即動手配置，告別緩慢的依賴下載，享受絲滑的構建體驗吧！

提示：配置完成后，別忘了運行./gradlew build驗證效果，并分享給你的團隊成員！

以上就是Gradle配置國內(nèi)鏡像加速指南(最全最詳細)的詳細內(nèi)容，更多關于Gradle配置國內(nèi)鏡像的資料請關注腳本之家其它相關文章！

最新評論