详解gradle脚本插入项目规范及作用

嘉小华
195 阅读4分钟

在 Gradle 构建中使用 apply from: 'xxx.gradle' 插入脚本的位置至关重要，它会直接影响脚本的作用范围、执行时机、可访问的上下文（如变量、对象）以及是否会被重复执行。

以下是不同插入位置的关键区别分析，帮你清晰理解：

核心差异点：

  1. 作用范围 (Scope)：  脚本在哪一级的 build.gradle 中被 apply，它就拥有哪一级的项目上下文 (project 对象) 。
  2. 执行时机 (Timing)：  所有 apply from: 都在 配置阶段 执行。但在哪个项目的配置阶段执行，取决于它写在哪个 build.gradle 里。
  3. 可见性/可用性 (Visibility)：  脚本中定义的变量、方法、任务，其可见性取决于它在哪个作用域被定义。
  4. 执行次数：  取决于它被 apply 的 build.gradle 文件在配置阶段被执行多少次（通常每个项目/模块的 build.gradle 在每次构建中只执行一次配置）。

具体插入位置分析：

  1. 插入在 settings.gradle 文件中

    • 作用范围：  拥有 Settings 对象的上下文（不是 Project 对象）。settings.gradle 主要管理项目结构。

    • 执行时机：  初始化阶段（Gradle 生命周期的第一个阶段）。

    • 典型用途：

      • 在项目结构确定前进行一些全局初始化或检查。
      • 根据条件动态决定包含哪些项目（模块）。
      • 定义一些在项目配置之前就需要可用的全局属性或方法（供后续 build.gradle 使用）。

    • 示例 (settings.gradle):

      // 在初始化阶段就加载一个脚本，定义一个全局可用的方法或属性
apply from: 'gradleScripts/globalInit.gradle'

// 假设 globalInit.gradle 定义了 projectCount() 方法
println "This build includes ${projectCount()} projects" // 在 settings.gradle 中使用

include ':app'
include ':lib'

    • 重要限制：

      • 在这里 apply 的脚本无法访问或配置具体的项目（如 app 模块） ，因为项目对象 (project) 还没创建。
      • 定义的属性/方法需要特殊方式（如 ext 或 gradle.ext）才能在后续的 build.gradle 中访问。

  2. 插入在 项目级 (root) build.gradle 文件中

    • 作用范围：  拥有 根项目 (rootProject) 的上下文。这是最常见的位置之一。

    • 执行时机：  配置阶段，且是最早执行的 build.gradle（在子模块的 build.gradle 之前）。

    • 典型用途：

      • 定义所有模块共享的依赖版本号（使用 ext 或 buildscript.ext）。
      • 配置所有模块共用的仓库 (repositories)。
      • 定义所有模块都需要执行的自定义任务或逻辑。
      • 应用对整个项目有效的插件或配置（如代码质量检查插件、发布插件）。
      • 配置 buildscript 块（定义 Gradle 插件依赖的位置）。

    • 示例 (root build.gradle):

      // 1. 定义所有模块共享的版本变量
ext {
    kotlinVersion = '1.8.22'
    retrofitVersion = '2.9.0'
}

// 2. 应用一个脚本，该脚本为所有子项目添加一个公共任务 (如生成报告)
apply from: 'gradleScripts/commonTasks.gradle'

// 3. 配置所有子项目的公共仓库
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

// 4. 配置 buildscript 依赖 (插件依赖)
buildscript {
    apply from: 'gradleScripts/dependencyVersions.gradle' // 脚本里定义了插件版本
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:$agpVersion" // 使用脚本中定义的 agpVersion
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
    }
}

    • 优势：

      • 代码复用：  避免在每个子模块重复相同的配置。
      • 集中管理：  统一控制核心依赖版本、仓库地址等。
      • 最先执行：  确保共享配置在子模块配置之前可用。

  3. 插入在 模块级 (module) build.gradle 文件中

    • 作用范围：  拥有当前模块项目 (project) 的上下文。这是另一个最常见的位置。

    • 执行时机：  配置阶段，在根项目 build.gradle 配置完成后，按照 settings.gradle 定义的顺序执行。

    • 典型用途：

      • 应用只针对特定模块的自定义配置或任务（如 app 模块特有的资源处理、library 模块特有的发布任务）。
      • 抽取模块内部复杂的配置逻辑，保持主 build.gradle 文件简洁。
      • 根据模块属性（如 flavor, buildType）动态加载不同的配置脚本。

    • 示例 (app/build.gradle):

      plugins {
    id 'com.android.application'
    id 'kotlin-android'
}

// 应用一个脚本，专门配置 app 模块的 Android 相关设置
apply from: '../gradleScripts/appAndroidConfig.gradle'

// 应用一个脚本，为 app 模块添加一个自定义的 APK 重命名任务
apply from: '../gradleScripts/appCustomTasks.gradle'

dependencies {
    implementation project(':mylibrary')
    implementation "com.squareup.retrofit2:retrofit:$rootProject.retrofitVersion" // 使用根项目定义的版本
    // ... 其他依赖
}

    • 关键点：

      • 可以访问根项目通过 ext 定义的全局变量 (rootProject.xxx 或 project.rootProject.xxx)。
      • 可以访问当前模块特有的属性和配置（android 块里的内容、模块路径等）。
      • 插入的位置顺序很重要：如果脚本 A 定义了变量或方法，脚本 B 要使用它们，那么 apply A 必须在 apply B 之前。

位置选择总结 & 最佳实践：

插入位置作用范围执行时机主要用途是否推荐
settings.gradleSettings 对象初始化阶段项目结构决策、极早期全局初始化⭐️ (特定场景)
项目级 build.gradle根项目 (rootProject)配置阶段 (最早)定义全局依赖版本、公共仓库、所有模块共享的任务/逻辑、buildscript 配置⭐️⭐️⭐️⭐️⭐️ (强烈推荐)
模块级 build.gradle当前模块项目 (project)配置阶段 (晚于根项目)模块特有配置、抽取复杂模块逻辑、模块特有任务、依赖根项目全局变量⭐️⭐️⭐️⭐️⭐️ (强烈推荐)

通俗选择指南：

  1. 所有模块都要用的东西 (版本号、公共仓库、全局任务)：  放在项目级 (root) build.gradle 里 apply 你的 xxx.gradle 脚本。
  2. 只有某个特定模块才需要的东西 (比如 app 模块的签名配置、library 模块的发布脚本)：  放在该模块的 build.gradle 里 apply 你的 xxx.gradle 脚本。
  3. 需要在决定包含哪些模块之前就做的事情 (非常少见)：  考虑放在 settings.gradle 里 apply。

插入顺序很重要：

  • 在同一个 build.gradle 文件中，apply from: 'A.gradle' 必须在 apply from: 'B.gradle' 之前，如果 B.gradle 依赖 A.gradle 中定义的变量或方法。
  • 在模块级脚本中访问根项目定义的全局变量 (rootProject.ext.xxx)，确保根项目的 build.gradle 已经执行过（这是自动保证的，因为根项目先配置）。

路径问题：

  • 在项目级 build.gradle 中 apply from: 'gradleScripts/xxx.gradle'，路径是相对于项目根目录。

  • 在模块级 build.gradle (如 app/build.gradle) 中 apply from: '../gradleScripts/xxx.gradle'，路径是相对于当前模块目录 (app/)。通常使用 ../ 回到根目录再找 gradleScripts/ 目录是常见做法。也可以使用绝对路径 rootProject.projectDir。

    // 在模块 build.gradle 中，推荐使用根目录相对路径
apply from: "${rootProject.projectDir}/gradleScripts/xxx.gradle"

结论：

选择 apply from: 'xxx.gradle' 的位置，本质是选择你想让这段脚本在哪个作用域 (哪个 Project)  和 时机 (相对哪个配置步骤)  执行。理解 Gradle 生命周期（初始化 -> 配置 -> 执行）和各 build.gradle 文件的执行顺序是关键。项目级用于全局共享，模块级用于特定模块定制，settings.gradle 用于极早期初始化

avatar
文章
阅读
粉丝