前言

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

解決方案：配置國(guó)內(nèi)鏡像源，將依賴下載請(qǐng)求重定向到國(guó)內(nèi)的鏡像服務(wù)器，顯著提升下載速度，縮短構(gòu)建時(shí)間。

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

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

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

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

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

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

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

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

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

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

步驟：

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

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

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

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

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

        // 如果項(xiàng)目需要，可以保留對(duì)Google等特定倉(cāng)庫(kù)的引用
        // google()
        // gradlePluginPortal()
    }

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

優(yōu)點(diǎn)：

• 一勞永逸，所有項(xiàng)目自動(dòng)生效。
• 無(wú)需修改每個(gè)項(xiàng)目的build.gradle文件。

缺點(diǎn)：

• 如果團(tuán)隊(duì)協(xié)作，其他成員也需要單獨(dú)配置。
• 可能影響某些需要訪問(wèn)原始倉(cāng)庫(kù)的特殊項(xiàng)目。

方法二：項(xiàng)目級(jí)配置（推薦用于團(tuán)隊(duì)協(xié)作）

適用于單個(gè)項(xiàng)目，配置寫(xiě)在項(xiàng)目文件中，團(tuán)隊(duì)成員克隆項(xiàng)目后自動(dòng)生效。

步驟：

• 打開(kāi)項(xiàng)目的build.gradle文件（通常是根項(xiàng)目的build.gradle）。
• 找到repositories塊，注釋或刪除原有的jcenter()和mavenCentral()。
• 添加國(guó)內(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)先使用國(guó)內(nèi)鏡像
        maven { url 'https://maven.aliyun.com/repository/public' }
        // 可以添加多個(gè)鏡像源，Gradle會(huì)按順序嘗試
        maven { url 'https://repo.huaweicloud.com/repository/maven/' }
        maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }

        // 保留必要的官方倉(cāng)庫(kù)
        google() // Android項(xiàng)目需要
        gradlePluginPortal() // Gradle插件需要
    }
}

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

優(yōu)點(diǎn)：

• 配置隨項(xiàng)目版本控制，團(tuán)隊(duì)成員共享。
• 不影響其他項(xiàng)目的構(gòu)建環(huán)境。

缺點(diǎn)：

每個(gè)項(xiàng)目都需要單獨(dú)配置。

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

Gradle 5.0 引入了settings.gradle中的dependencyResolutionManagement，是官方推薦的集中管理依賴和倉(cāng)庫(kù)的方式。

步驟：

在項(xiàng)目根目錄的settings.gradle文件中添加：

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

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

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

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

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

// 包含子項(xiàng)目（如果有）
include 'app'
// include 'library'

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

優(yōu)點(diǎn)：

• 官方推薦，結(jié)構(gòu)清晰，易于維護(hù)。
• 集中管理所有模塊的倉(cāng)庫(kù)配置。
• 支持更復(fù)雜的依賴解析策略。

缺點(diǎn)：

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

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

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

步驟：

在gradle.properties文件中（項(xiàng)目級(jí)或用戶級(jí)）添加：

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

# 或者直接設(shè)置倉(cāng)庫(kù)URL（不推薦，不如方法三靈活）
# systemProp.maven.repo.remote=https://maven.aliyun.com/repository/public

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

四、驗(yàn)證配置是否生效

配置完成后，如何確認(rèn)鏡像源已成功使用？

方法 1：查看構(gòu)建日志

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

方法 2：檢查網(wǎng)絡(luò)請(qǐng)求

使用網(wǎng)絡(luò)監(jiān)控工具（如 Wireshark、Fiddler）或?yàn)g覽器開(kāi)發(fā)者工具，觀察 Gradle 構(gòu)建時(shí)的 HTTP 請(qǐng)求目標(biāo)地址。

方法 3：對(duì)比構(gòu)建時(shí)間

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

五、常見(jiàn)問(wèn)題與解決方案

問(wèn)題 1：配置后仍然從國(guó)外倉(cāng)庫(kù)下載

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

問(wèn)題 2：某些依賴在鏡像中找不到

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

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

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

問(wèn)題 3：Android 項(xiàng)目提示“Failed to resolve: androidx.xxx”

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

配置示例：

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

問(wèn)題 4：Gradle 版本過(guò)低，不支持settings.gradle配置？

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

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

使用build.gradle項(xiàng)目級(jí)配置。

六、最佳實(shí)踐與建議

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

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

團(tuán)隊(duì)項(xiàng)目用項(xiàng)目級(jí)配置：確保環(huán)境一致性，避免“在我機(jī)器上能跑”的問(wèn)題。

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

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

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

文檔化配置：在項(xiàng)目 README 中說(shuō)明倉(cāng)庫(kù)配置，方便新成員加入。

七、總結(jié)

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

核心要點(diǎn)：

• 阿里云鏡像是首選。
• settings.gradle 是未來(lái)趨勢(shì)。
• 項(xiàng)目級(jí)配置利于團(tuán)隊(duì)協(xié)作。
• 全局配置適合個(gè)人使用。

立即動(dòng)手配置，告別緩慢的依賴下載，享受絲滑的構(gòu)建體驗(yàn)吧！

提示：配置完成后，別忘了運(yùn)行./gradlew build驗(yàn)證效果，并分享給你的團(tuán)隊(duì)成員！

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

最新評(píng)論