Gradle 全局配置使用

一、原理

Gradle 查找依赖时会按仓库声明顺序依次搜索 ，把本地仓库（mavenLocal()）放在所有远程仓库前面，即可实现优先使用本地依赖，本地不存在时才从远程下载。

二、配置全局初始化文件（关键步骤）

全局配置文件对所有 Gradle 项目生效，无需逐个项目修改。

1. 定位 / 创建全局配置文件

Gradle 全局初始化文件路径：

Windows ：C:\Users\<用户名>\.gradle\init.gradle（或init.gradle.kts）
Linux/macOS ：~/.gradle/init.gradle（或init.gradle.kts）

如果文件不存在，直接手动创建（无后缀，文件名固定为init.gradle）。

2. 编写全局仓库配置

以下提供两种常用 DSL 写法，任选其一：

写法 1：Groovy DSL（`init.gradle`）

groovy 复制代码

 // Gradle 全局初始化配置文件
// 路径：Windows(C:\Users\<用户名>\.gradle\init.gradle) / Linux/macOS(~/.gradle/init.gradle)
// 作用：全局优先使用本地Maven仓库，搭配国内镜像加速远程依赖下载

// 1. 全局项目仓库配置（所有项目生效）
allprojects {
    repositories {
        // ==================== 核心：优先使用本地Maven仓库 ====================
        mavenLocal {
            // 替换下方路径为你的本地Maven仓库实际路径（删除注释后生效）
            //url = uri('D:/maven-repository')  // Windows 配置
            //url = uri('/Users/yourname/Documents/maven-repo') // macOS/Linux示例
            // 若使用默认路径（~/.m2/repository），可删除上面的url配置行
        }

        // ==================== 国内镜像仓库（加速远程下载） ====================
        // 阿里云中央仓库
        maven { url 'https://maven.aliyun.com/repository/public' }
        // 阿里云Google仓库（适配Android/Compose）
        maven { url 'https://maven.aliyun.com/repository/google' }
        // 阿里云Gradle插件仓库
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        // 阿里云Spring仓库（如需Spring相关依赖）
        maven { url 'https://maven.aliyun.com/repository/spring' }
        // 阿里云Spring插件仓库
        maven { url 'https://maven.aliyun.com/repository/spring-plugin' }

        // ==================== 官方仓库（兜底） ====================
        google()              // Android/Compose官方仓库
        mavenCentral()        // 中央仓库
        gradlePluginPortal()  // Gradle插件仓库
        maven { url 'https://jitpack.io' } // 第三方开源库仓库（可选）
    }

    // 可选：依赖下载超时配置（解决网络慢导致的下载失败）
    configurations.all {
        resolutionStrategy {
            cacheDynamicVersionsFor 10, 'minutes'
            cacheChangingModulesFor 10, 'minutes'
        }
        // 超时时间设置
        setTimeout(300) // 单位：秒
    }
}

// 2. Gradle插件仓库配置（影响插件下载顺序）
settingsEvaluated { settings ->
    settings.pluginManagement {
        repositories {
            // 插件优先从本地仓库查找
            mavenLocal {
                // 同上面的本地仓库路径，如需自定义则取消注释并修改
                // url = uri('D:/maven-repository')  //Windows示例
                // url = uri('/Users/yourname/Documents/maven-repo') // macOS/Linux示例
            }
            // 插件镜像仓库
            maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
            // 官方插件仓库兜底
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    }
}

// 3. 可选：构建优化配置
gradle.projectsLoaded {
    rootProject.allprojects {
        buildDir = "${rootProject.rootDir}/.gradle-build/${project.name}"
    }
}

// 4. 可选：打印依赖查找日志（验证本地仓库是否生效）
gradle.addBuildListener(new BuildListener() {
    @Override
    void buildStarted(Gradle gradle) {
        println "===== Gradle 构建开始：优先使用本地仓库 ====="
    }

    @Override
    void settingsEvaluated(Settings settings) {}

    @Override
    void projectsLoaded(Gradle gradle) {}

    @Override
    void projectsEvaluated(Gradle gradle) {}

    @Override
    void buildFinished(BuildResult result) {
        println "===== Gradle 构建结束：本地仓库优先配置已生效 ====="
    }
})

写法 2：Kotlin DSL（`init.gradle.kts`）

kotlin 复制代码

 // Gradle 全局初始化配置文件（Kotlin DSL）
// 路径：Windows(C:\Users\<用户名>\.gradle\init.gradle.kts) / Linux/macOS(~/.gradle/init.gradle.kts)
// 作用：全局优先使用本地Maven仓库，搭配阿里云镜像加速远程依赖下载

// 1. 全局项目仓库配置（所有Gradle项目生效）
allprojects {
    repositories {
        // ==================== 核心：优先使用本地Maven仓库 ====================
        mavenLocal {
            // 替换下方路径为你的本地Maven仓库实际路径（删除注释后生效）
            // url = uri("D:/maven-repository") // Windows示例
            // url = uri("/Users/yourname/.m2/repository") // macOS/Linux示例
            // 若使用默认路径（~/.m2/repository），直接注释掉url配置行即可
        }

        // ==================== 国内镜像仓库（加速远程下载） ====================
        // 阿里云中央仓库（适配Java/Kotlin基础依赖）
        maven("https://maven.aliyun.com/repository/public")
        // 阿里云Google仓库（适配Android/Compose核心依赖）
        maven("https://maven.aliyun.com/repository/google")
        // 阿里云Gradle插件仓库（适配Android Gradle插件）
        maven("https://maven.aliyun.com/repository/gradle-plugin")
        // 阿里云Spring仓库（如需Spring相关依赖，可选）
        maven("https://maven.aliyun.com/repository/spring")
        // 阿里云Spring插件仓库（可选）
        maven("https://maven.aliyun.com/repository/spring-plugin")
        // JitPack（第三方开源库，如GitHub依赖，可选）
        maven("https://jitpack.io")

        // ==================== 官方仓库（兜底，不可删除） ====================
        google()              // Android/Compose官方核心仓库
        mavenCentral()        // Maven中央仓库
        gradlePluginPortal()  // Gradle插件官方仓库
    }

    // 可选：依赖下载超时&缓存优化（解决Android依赖下载慢/失败）
    configurations.all {
        resolutionStrategy {
            // 动态版本缓存时间
            cacheDynamicVersionsFor(10, "minutes")
            // 快照版本缓存时间
            cacheChangingModulesFor(10, "minutes")
        }
        // 依赖下载超时时间（单位：秒）
        setTimeout(300)
    }
}

// 2. Gradle插件仓库配置（影响Android Gradle插件、自定义插件的下载顺序）
settingsEvaluated {
    pluginManagement {
        repositories {
            // 插件优先从本地仓库查找
            mavenLocal {
                // 同上面的本地仓库路径，如需自定义则取消注释并修改
                // url = uri("D:/maven-repository") //Windows示例
                // url = uri("/Users/yourname/.m2/repository") // macOS/Linux示例
            }
            // 插件镜像仓库
            maven("https://maven.aliyun.com/repository/gradle-plugin")
            // 官方插件仓库兜底
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    }
}

// 3. 可选：Android项目构建目录优化（避免模块间构建目录分散）
gradle.projectsLoaded {
    rootProject.allprojects {
        buildDir = file("${rootProject.rootDir}/.gradle-build/${project.name}")
    }
}

// 4. 可选：打印构建日志（验证本地仓库配置是否生效）
gradle.addBuildListener(object : BuildListener {
    override fun buildStarted(gradle: Gradle) {
        println("===== Gradle 构建开始：优先使用本地仓库（Kotlin DSL配置） =====")
    }

    override fun settingsEvaluated(settings: Settings) {}
    override fun projectsLoaded(gradle: Gradle) {}
    override fun projectsEvaluated(gradle: Gradle) {}
    override fun buildFinished(result: BuildResult) {
        val status = if (result.failure == null) "成功" else "失败"
        println("===== Gradle 构建结束：本地仓库优先配置已生效（构建${status}） =====")
    }
})