🐘

Gradle 镜像配置完全指南

现代化的构建工具 | Android/Java/Kotlin 必备

⏱️ 8分钟配置 🎯 适用于 Gradle 6.x/7.x/8.x 💻 全平台支持

📖 什么是 Gradle？

Gradle 是一个基于 Apache Ant 和 Apache Maven 概念的项目自动化构建工具，使用 Groovy 或 Kotlin DSL 来声明项目配置。它是 Android 官方推荐的构建工具。

灵活强大：支持多种编程语言和平台
性能优越：增量构建、构建缓存、并行执行
扩展性强：丰富的插件生态系统
Android 首选：Android Studio 默认构建工具

💡 为什么需要配置镜像源？

Gradle 默认从 Maven Central、JCenter 等国外仓库下载依赖，国内访问速度极慢，经常超时。配置国内镜像后，下载速度可提升50-100倍！特别是 Android 项目，首次构建可能需要下载几个 GB 的依赖。

🚀 方法一：项目级配置（推荐）

在项目的 build.gradle 或 build.gradle.kts 文件中配置。

Groovy DSL (build.gradle)

allprojects {
    repositories {
        // 优先使用阿里云镜像
        maven { url 'https://maven.aliyun.com/repository/public/' }
        maven { url 'https://maven.aliyun.com/repository/google/' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin/' }
        maven { url 'https://maven.aliyun.com/repository/jcenter/' }

        // 备用镜像
        maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }
        maven { url 'https://repo.huaweicloud.com/repository/maven/' }

        // 最后使用官方仓库（可选）
        mavenCentral()
        google()
    }
}

Kotlin DSL (build.gradle.kts)

allprojects {
    repositories {
        maven("https://maven.aliyun.com/repository/public/")
        maven("https://maven.aliyun.com/repository/google/")
        maven("https://maven.aliyun.com/repository/gradle-plugin/")
        maven("https://maven.aliyun.com/repository/jcenter/")

        maven("https://mirrors.cloud.tencent.com/nexus/repository/maven-public/")
        maven("https://repo.huaweicloud.com/repository/maven/")

        mavenCentral()
        google()
    }
}

Android 项目完整配置

在项目根目录的 build.gradle 中：

// Top-level build file
buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public/' }
        maven { url 'https://maven.aliyun.com/repository/google/' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin/' }
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.2.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.20"
    }
}

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

task clean(type: Delete) {
    delete rootProject.buildDir
}

⚙️ 方法二：全局配置（一劳永逸）

创建全局配置文件，对所有项目生效。

1. 创建 init.gradle 文件

在以下位置创建 init.gradle 文件：

Windows: C:\Users\你的用户名\.gradle\init.gradle
macOS/Linux: ~/.gradle/init.gradle

2. 添加以下内容

allprojects {
    repositories {
        def ALIYUN_REPOSITORY_URL = 'https://maven.aliyun.com/repository/public/'
        def ALIYUN_GOOGLE_URL = 'https://maven.aliyun.com/repository/google/'
        def ALIYUN_GRADLE_PLUGIN_URL = 'https://maven.aliyun.com/repository/gradle-plugin/'
        def ALIYUN_JCENTER_URL = 'https://maven.aliyun.com/repository/jcenter/'

        all { ArtifactRepository repo ->
            if (repo instanceof MavenArtifactRepository) {
                def url = repo.url.toString()
                if (url.startsWith('https://repo1.maven.org/maven2/')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_REPOSITORY_URL."
                    remove repo
                }
                if (url.startsWith('https://dl.google.com/dl/android/maven2/')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_GOOGLE_URL."
                    remove repo
                }
                if (url.startsWith('https://plugins.gradle.org/m2/')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_GRADLE_PLUGIN_URL."
                    remove repo
                }
                if (url.startsWith('https://jcenter.bintray.com/')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_JCENTER_URL."
                    remove repo
                }
            }
        }

        maven { url ALIYUN_REPOSITORY_URL }
        maven { url ALIYUN_GOOGLE_URL }
        maven { url ALIYUN_GRADLE_PLUGIN_URL }
        maven { url ALIYUN_JCENTER_URL }
    }

    buildscript {
        repositories {
            maven { url 'https://maven.aliyun.com/repository/public/' }
            maven { url 'https://maven.aliyun.com/repository/google/' }
            maven { url 'https://maven.aliyun.com/repository/gradle-plugin/' }
        }
    }
}

🔥 方法三：Gradle Wrapper 加速

加速 Gradle 本体的下载（第一次运行 ./gradlew 时）。

修改 gradle-wrapper.properties

编辑项目中的 gradle/wrapper/gradle-wrapper.properties 文件：

# 原始配置
# distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

# 改为阿里云镜像
distributionUrl=https\://mirrors.aliyun.com/macports/distfiles/gradle/gradle-8.5-bin.zip

# 或腾讯云镜像
# distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip

⚠️ 注意版本号

确保镜像源中有对应的 Gradle 版本。如果镜像源没有最新版本，可以先从官方下载到本地，然后使用 file:// 协议指向本地文件。

🔧 常用镜像源对比

镜像源	覆盖度	速度	推荐度
阿里云	⭐⭐⭐⭐⭐	⚡⚡⚡⚡⚡	✅ 首选
腾讯云	⭐⭐⭐⭐	⚡⚡⚡⚡	✅ 推荐
华为云	⭐⭐⭐⭐	⚡⚡⚡⚡	✅ 推荐

🏢 企业私有仓库配置

如果公司有内部 Maven 私服（如 Nexus、Artifactory）：

allprojects {
    repositories {
        // 优先使用公司私服
        maven {
            url 'https://your-company-nexus.com/repository/maven-public/'
            credentials {
                username = project.findProperty("nexusUsername") ?: ""
                password = project.findProperty("nexusPassword") ?: ""
            }
        }

        // 然后使用公共镜像
        maven { url 'https://maven.aliyun.com/repository/public/' }

        mavenCentral()
        google()
    }
}

在 gradle.properties 中配置凭证：

nexusUsername=your-username
nexusPassword=your-password

❓ 常见问题

Q1: Gradle Sync 还是很慢怎么办？

多重优化方案：

确认镜像配置生效：查看构建日志中的下载地址
清除缓存：删除 ~/.gradle/caches 目录
启用并行构建：在 gradle.properties 中添加：
org.gradle.parallel=true org.gradle.daemon=true org.gradle.caching=true org.gradle.configureondemand=true
增加 Gradle 内存：org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=512m

Q2: 提示 "Could not find xxx.jar"

排查步骤：

检查依赖声明是否正确
确认镜像源中有该依赖（某些私有包可能没有）
尝试添加更多镜像源作为备用
使用 --refresh-dependencies 强制刷新

Q3: Android Studio 中如何配置？

三个位置都需要配置：

项目级 build.gradle（buildscript 和 allprojects）
模块级 app/build.gradle（repositories）
全局 ~/.gradle/init.gradle（推荐）

Q4: Gradle 插件下载失败

解决方案：

// 在 settings.gradle 中配置
pluginManagement {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin/' }
        maven { url 'https://maven.aliyun.com/repository/public/' }
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

Q5: 镜像源同步延迟导致找不到最新版本

临时解决：

等待镜像同步（通常10-30分钟）
临时添加官方仓库：
repositories { maven { url 'https://maven.aliyun.com/repository/public/' } mavenCentral() // 官方仓库作为后备 }
或者使用 --refresh-dependencies 参数

🎓 高级技巧

1. 查看依赖树

# 查看所有依赖
./gradlew dependencies

# 查看特定配置的依赖
./gradlew app:dependencies --configuration releaseRuntimeClasspath

2. 强制刷新依赖

./gradlew build --refresh-dependencies

3. 离线模式构建

适合已经下载过所有依赖的情况：

./gradlew build --offline

4. 查看构建缓存

# 查看缓存目录
ls -lh ~/.gradle/caches/

# 清理缓存（慎用）
./gradlew clean cleanBuildCache

5. 配置仓库优先级

Gradle 按照声明顺序查找依赖，把最快的镜像放在最前面：

repositories {
    maven { url 'https://maven.aliyun.com/repository/public/' }  // 第一优先
    maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }  // 第二优先
    mavenCentral()  // 最后备选
}

🚄 Gradle 性能优化完整配置

在项目根目录的 gradle.properties 文件中：

# 并行构建
org.gradle.parallel=true

# 启用 Gradle 守护进程
org.gradle.daemon=true

# 按需配置
org.gradle.configureondemand=true

# 启用构建缓存
org.gradle.caching=true

# 增加 JVM 内存（根据电脑配置调整）
org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

# Kotlin 编译器配置（如果使用 Kotlin）
kotlin.incremental=true
kotlin.incremental.js=true
kotlin.caching.enabled=true

# Android 构建优化
android.enableJetifier=true
android.useAndroidX=true
android.enableBuildCache=true

📦 常用 Gradle 命令速查

# 清理项目
./gradlew clean

# 构建项目
./gradlew build

# 编译（不运行测试）
./gradlew assemble

# 运行测试
./gradlew test

# 查看所有任务
./gradlew tasks

# 查看项目信息
./gradlew projects

# 查看依赖
./gradlew dependencies

# 升级 Gradle Wrapper
./gradlew wrapper --gradle-version 8.5

# Android 安装到设备
./gradlew installDebug

# Android 生成 Release APK
./gradlew assembleRelease

✨ 最佳实践

✅ Gradle 配置建议

使用全局 init.gradle：一次配置，所有项目生效
提交 Gradle Wrapper：确保团队使用相同的 Gradle 版本
定期清理缓存：避免占用过多磁盘空间
使用 gradle.properties：统一管理配置，不要硬编码
锁定依赖版本：使用精确版本号，避免 +
启用构建缓存：大幅提升增量构建速度

🔗 相关资源

💡 配置成功了吗？

如果这篇教程对你有帮助，欢迎分享给其他 Android/Java 开发者！遇到问题可以到关于页面反馈。