1.1 Gradle 解决的问题#

一个真实项目通常需要完成以下步骤：

1
读取配置 → 解析插件与依赖 → 生成源码或资源 → 编译 → 测试与检查 → 打包 → 发布

如果这些步骤依赖人工执行，容易出现顺序错误、环境差异、依赖遗漏和不可复现。Gradle 将它们组织成任务图，并根据输入、输出和依赖关系决定执行顺序。

1.2 Gradle 的主要特点#

• 声明式配置：描述项目、依赖、插件和任务关系。
• 可编程 DSL：可使用 Kotlin DSL 或 Groovy DSL 表达复杂逻辑。
• 插件化：Java、Kotlin、Android、发布等能力通过插件提供。
• 依赖管理：支持 Maven、Ivy、本地仓库和项目依赖。
• 增量构建：输入输出没有变化时跳过任务。
• 构建缓存：复用本机或其他机器生成的任务输出。
• 配置缓存：复用构建配置结果，减少后续启动成本。
• 多项目构建：管理多个相关模块和跨模块任务关系。
• Wrapper：固定 Gradle 版本，使开发机和 CI 使用相同环境。

1.3 Gradle 不只是“编译命令包装器”#

编译器只负责把源代码转换成字节码或其他目标产物；依赖管理器主要负责查找和下载组件；CI 系统负责在指定环境中执行流水线。Gradle 的职责更宽，它把这些步骤组织成一个可观察、可组合的构建模型：

1
源码、资源、配置、依赖、工具链
2
                ↓
3
        Gradle 构建模型与任务图
4
                ↓
5
编译、测试、检查、代码生成、打包、发布和报告

因此，Gradle 通常同时承担以下角色：

1.4 一个 Gradle 构建是怎样工作的#

以执行 build 为例，可以把一次构建拆成以下步骤：

1. 定位构建入口：Gradle 从当前目录寻找 settings.gradle.kts 或 settings.gradle。
2. 初始化构建：确定根项目、子项目、插件管理和全局构建设置。
3. 配置项目：应用插件，创建 Configuration、Source Set、Extension 和 Task。
4. 解析请求：根据命令行选择 build 需要的任务，并展开任务依赖。
5. 解析依赖：针对具体 Configuration 选择仓库、版本和变体。
6. 判断任务状态：检查任务输入、输出、依赖结果和缓存命中情况。
7. 执行必要任务：编译、测试、检查和打包。
8. 报告结果：输出日志、报告、构件和失败原因。

可以用下面的关系理解它：

1
用户命令
2
   ↓
3
任务选择
4
   ↓
5
任务依赖图
6
   ↓
7
输入与输出快照 ──→ up-to-date / cache hit
8
   ↓                         ↓
9
需要执行的任务  ←────── 复用已有结果
10
   ↓
11
构建产物与报告

1.5 Gradle 的输入、规则与输出#

任何可维护的构建都可以从三个问题开始：

• 输入是什么：源码、资源、依赖、编译参数、环境属性、工具链和版本。
• 规则是什么：插件约定、任务依赖、变体选择、版本约束和发布策略。
• 输出是什么：字节码、测试报告、覆盖率报告、JAR、APK、AAB 或发布元数据。

例如 Java 编译任务的抽象关系是：

1
Java 源码 + 编译参数 + JDK + 类路径
2
                    ↓
3
                compileJava
4
                    ↓
5
             build/classes/java/main

如果输入发生变化，输出可能需要重新生成；如果输入没有变化，Gradle 可以将任务标记为 UP-TO-DATE 或从 Build Cache 恢复。自定义任务是否正确声明输入和输出，直接决定了增量构建、缓存和并行执行是否可靠。

1.6 Gradle 与周边工具的关系#

Gradle 不是孤立工作的。常见组合关系如下：

1
Gradle
2
├── Java Toolchain：选择 JDK 和编译工具
3
├── Kotlin Gradle Plugin：配置 Kotlin 编译
4
├── Android Gradle Plugin：配置 Android 变体和打包
5
├── JUnit、TestNG：执行测试
6
├── Checkstyle、JaCoCo、Lint：质量检查和报告
7
├── Maven/Ivy 仓库：解析和发布依赖
8
├── GitHub Actions/GitLab CI：提供持续集成环境
9
└── IDE：调用 Gradle 模型、任务和测试入口

这也是为什么“Gradle 能不能使用某个版本”不能只看 Gradle 本身。实际兼容性还受 JDK、插件、Android Studio、Kotlin、操作系统和仓库环境影响。

1.7 Gradle 的优势与代价#

优势

• 可以用统一模型覆盖从简单 Java 应用到大型多模块工程。
• 插件和 Convention Plugin 能把组织规范固化为可复用能力。
• 任务输入输出模型支持增量构建、缓存和并行执行。
• Kotlin DSL 提供较好的类型检查、补全和重构体验。
• 可同时支持本地开发、IDE、CI 和发布流程。

代价

• 学习成本高于单纯的脚本式构建工具。
• 插件、JDK、语言和框架之间存在兼容矩阵。
• 动态构建逻辑容易造成配置阶段变慢或行为隐式。
• 依赖变体、传递依赖和缓存问题需要系统化诊断。
• 构建脚本本身也是代码，需要测试、审查和版本治理。

不要只因为 Gradle 功能强大就把所有逻辑都放进构建脚本。构建逻辑应保持可读、可验证，并把复杂业务能力放到合适的独立工具或服务中。

** 哪些场景适合使用 Gradle**

Gradle 特别适合以下场景：

• 项目需要多个编译、测试、生成和发布步骤协同执行。
• 依赖关系复杂，且需要处理传递依赖、平台和变体。
• 仓库包含多个相互依赖的模块。
• 团队希望通过缓存和增量构建缩短反馈时间。
• 需要将本地构建、IDE 和 CI 的命令统一起来。
• 需要构建 Java/Kotlin Library、Android 应用或可发布构件。

哪些场景不应过度使用 Gradle

以下场景不一定需要引入复杂的 Gradle 逻辑：

• 只有一条固定编译命令且没有依赖管理需求的小型实验。
• 一个简单脚本即可完成的文件复制或静态资源处理。
• 已经稳定运行、团队也不需要扩展的 Maven 项目。
• 需要复杂部署编排、审批和运行时状态管理的系统。

Gradle 可以调用外部工具，但它不是通用工作流平台、应用运行时或部署控制面。构建脚本应负责“构建和交付输入”，不应替代业务系统和生产运维平台。

2.1 Build#

一次 Gradle Build 是 Gradle 对一个构建定义进行初始化、配置和执行的完整过程。一个 Build 可以包含一个项目，也可以包含多个项目。

2.2 Project#

Project 是可构建的软件单元，例如 Java 应用、Java Library、Android App 模块、Android Library 模块或只负责聚合任务的根项目。多项目构建中通常存在一个根项目和多个子项目。

2.3 Task#

Task 是 Gradle 的基本工作单元，例如：

• compileJava：编译 Java 源码。
• test：运行测试。
• jar：生成 JAR。
• build：完成构建和验证。
• publish：发布构件。
• assembleDebug：生成 Android Debug 产物。

Task 可以依赖其他 Task。Gradle 根据依赖关系构建有向无环图，再执行用户请求所需的节点。

2.4 Plugin#

Plugin 用来给项目添加能力、任务、扩展对象和约定：

1
plugins {
2
    java
3
    application
4
    `maven-publish`
5
}

应用 java 插件后，项目会获得标准 Source Set、编译任务、测试任务和 JAR 任务。

2.5 Dependency#

Dependency 是项目在编译、运行、测试或构建过程中需要的外部或内部组件：

1
dependencies {
2
    implementation("com.google.guava:guava:33.5.0-jre")
3
    testImplementation("org.junit.jupiter:junit-jupiter:6.0.3")
4
}

依赖不只包含 JAR。Gradle 还会处理依赖元数据、传递依赖、能力、属性和变体。

2.6 Configuration#

Configuration 是一组具有特定用途的依赖集合或可发布变体，例如 implementation、api、compileClasspath、runtimeClasspath 和 testImplementation。

不要把 Configuration 简单理解成“依赖列表”。它同时承担声明、解析和变体选择等角色。

2.7 Build Script 与 Settings#

构建脚本用于声明插件、依赖、任务和项目配置：

1
build.gradle.kts    Kotlin DSL
2
build.gradle        Groovy DSL

Settings 负责定义整个构建的边界和全局结构，常见职责包括根项目名称、子项目、插件仓库、依赖仓库策略、Version Catalog、Composite Build 和 Build Cache。

2.8 一句话心智模型#

1
Settings 决定“构建里有什么”
2
Project 决定“每个模块怎么构建”
3
Plugin 提供“可用能力与约定”
4
Task 表示“需要完成的工作”
5
Dependency 提供“构建需要的组件”

2.9 Gradle 的对象关系#

Gradle 的核心对象不是彼此孤立的，可以用下面的关系图理解：

1
Gradle Build
2
├── Settings
3
│   ├── rootProject
4
│   ├── included projects
5
│   ├── pluginManagement
6
│   ├── dependencyResolutionManagement
7
│   └── included builds
8
└── Projects
9
    ├── plugins
10
    ├── extensions
11
    ├── configurations
12
    ├── source sets
13
    ├── dependencies
14
    └── tasks

一个 Project 中的 Plugin 通常会创建或配置其他对象：

1
应用 java 插件
2
      ↓
3
创建 Source Set、Configuration、Extension 和标准 Task
4
      ↓
5
声明依赖、配置编译器和测试平台
6
      ↓
7
形成 compileJava → classes → test → check → build 的关系

这说明很多 Gradle 配置并不是独立开关，而是对对象模型中的某个对象进行配置。遇到配置项时，先问它属于 Settings、Project、Plugin、Extension、Configuration 还是 Task，通常更容易找到正确写法。

2.10 Build、Project 与 Settings 的边界#

一个常见错误是把 Project 级配置放到 Settings，或把任务执行逻辑直接放到 Settings。判断位置时可以使用这个原则：

• 决定“有哪些项目”的配置放在 Settings。
• 决定“某个项目如何构建”的配置放在 Project。
• 决定“某一步如何执行”的配置放在 Task 或自定义 Task 类型。
• 决定“多个项目如何统一”的逻辑放在 Convention Plugin。

2.11 Task 图：依赖关系不是脚本顺序#

执行以下命令：

1
.\gradlew.bat build

Gradle 不会简单地从上到下执行构建脚本中的每一行，而是根据用户请求和任务依赖构造任务图。一个简化的 Java 构建图可能是：

1
compileJava ──→ classes ──→ jar ──→ assemble
2
      │                         │
3
      └────→ test ──→ check ────┘
4
                         ↓
5
                       build

其中箭头表示“必须先完成”。build 是生命周期任务，通常通过依赖关系聚合编译、测试、检查和打包任务；它本身不一定包含大量实际动作。

查看任务图的常用方式：

1
.\gradlew.bat build --dry-run
2
.\gradlew.bat tasks --all
3
.\gradlew.bat build --info

--dry-run 只展示将执行的任务，不执行任务动作；--info 可以帮助观察任务跳过、依赖解析和执行原因。

2.12 dependsOn、mustRunAfter 与 finalizedBy#

这三个 API 表达的关系不同：

1
taskB {
2
    dependsOn(taskA)
3
}
4

5
taskC {
6
    mustRunAfter(taskA)
7
}
8

9
taskD {
10
    finalizedBy(taskE)
11
}

• dependsOn：B 需要 A，执行 B 时会把 A 加入任务图。
• mustRunAfter：A 和 C 都在任务图中时，C 必须排在 A 后面；它不会自动加入 A。
• finalizedBy：任务结束后执行终结任务，常用于清理或生成辅助报告。

如果任务 B 真正读取任务 A 的输出，优先使用 dependsOn 和文件 Provider 表达关系，而不是只写 mustRunAfter。只有顺序相关但没有数据依赖时，才使用顺序规则。

2.13 Task 配置与 Task 执行#

下面两段代码发生在不同阶段：

1
tasks.register("demo") {
2
    group = "example"
3
    description = "示例任务"
4

5
    doLast {
6
        println("任务动作执行")
7
    }
8
}

• group 和 description 是任务配置，通常在 Configuration 阶段处理。
• doLast 中的代码是任务动作，在 Execution 阶段处理。

不要在任务配置阶段读取大量文件、访问网络或运行外部程序。应把这些行为放进任务动作，并把相关文件、参数和环境声明为输入，使 Gradle 能够判断任务是否需要执行。

2.14 声明式配置与命令式逻辑#

Gradle DSL 看起来像普通编程语言，但推荐的构建脚本仍应尽可能表达“目标状态”和“对象关系”：

1
tasks.withType<Test>().configureEach {
2
    useJUnitPlatform()
3
}

这比遍历所有任务、判断名称并立即修改对象更容易维护：

1
tasks.all {
2
    if (name.endsWith("Test")) {
3
        // 隐式匹配，容易受到插件变化影响
4
    }
5
}

命令式逻辑并非完全不能使用，但应限制在自定义插件或清晰封装的规则中，并避免依赖任务创建顺序、项目评估顺序或全局可变状态。

2.15 Dependency 与 Task Dependency 不是一回事#

这两个概念都叫“依赖”，但层次不同：

例如：

1
dependencies {
2
    implementation(project(":core"))
3
    implementation("com.google.guava:guava:33.5.0-jre")
4
}

这段代码声明的是 Project 和 External Dependency，不等于声明某个 Task 的执行顺序。项目依赖会影响类路径和变体选择，也可能间接影响任务图，但两者不能互相替代。

2.16 Configuration 的三种角色#

现代 Gradle 中，Configuration 通常可以从用途上分为三类：

1. Declarable：用于声明依赖，例如 implementation。
2. Resolvable：用于解析文件，例如 runtimeClasspath。
3. Consumable：用于向其他项目提供变体，例如 runtimeElements。

可以用一个简化例子表示：

1
implementation ──继承或参与──→ runtimeClasspath
2
                                     ↓
3
                               解析得到文件
4

5
java-library 项目 ──发布──→ apiElements / runtimeElements

不要随意把一个声明 Configuration 当作文件集合直接解析，也不要把所有依赖都塞进 compileClasspath。使用插件提供的标准 Configuration，通常比手工拼接类路径更安全。

2.17 Extension 与 Convention#

Plugin 往往通过 Extension 暴露配置入口：

1
application {
2
    mainClass = "com.example.App"
3
}
4

5
java {
6
    toolchain {
7
        languageVersion = JavaLanguageVersion.of(21)
8
    }
9
}

这里的 application {} 和 java {} 不是普通函数，而是插件创建的 Extension 或类型安全访问器。它们把用户配置传递给插件，再由插件创建或配置任务。

Convention 是团队对这些配置的默认约定，例如所有 Java Library 都使用 JDK 21、JUnit Platform 和统一的编译参数。Convention 应通过插件实现，而不是在根项目中隐式修改所有子项目。

2.18 项目路径与任务路径#

多项目构建中，项目和任务都有路径：

1
:                    根项目
2
:app                 app 子项目
3
:app:test            app 项目的 test 任务
4
:core:compileJava    core 项目的 Java 编译任务

执行指定模块任务：

1
.\gradlew.bat :app:test
2
.\gradlew.bat :core:compileJava

在脚本中引用跨项目任务时，应尽量使用 Provider 和类型安全 API；不要通过字符串拼接大量任务名称来隐藏模块关系。

3.1 Ant#

Ant 更接近命令式任务编排。开发者显式描述每一步执行什么、先后顺序是什么。它灵活，但大型构建容易出现重复 XML、手工任务关系和维护成本。

3.2 Maven#

Maven 使用 XML 和固定生命周期，强调约定优于配置。它的目录约定、生命周期和企业生态成熟，但复杂定制通常需要插件或冗长 XML。

3.3 Gradle#

Gradle 吸收了 Ant 的灵活性和 Maven 的依赖、仓库、约定思想，并提供任务图、插件、增量构建和缓存机制。

3.4 如何选择#

• 维护既有 Maven 项目：尊重现有工程，不要仅为“新”而迁移。
• Android：使用 Gradle 和 Android Gradle Plugin。
• 新建复杂 JVM、多模块或需要高度定制的项目：Gradle 通常更合适。
• 简单、稳定且团队更熟悉 Maven 的项目：Maven 仍然合理。

构建工具没有绝对优劣，真正重要的是可复现、可维护、可升级和团队可理解。

3.5 三种构建工具的核心模型#

表格只能帮助建立方向，不能替代对现有仓库的评估。一个成熟的 Maven 项目可能比一个缺少约定的 Gradle 项目更容易维护；一个简单的 Ant 构建也可能比过度抽象的 Gradle 构建更容易排错。

3.6 Ant 的工作方式#

Ant 构建通常通过 build.xml 定义 Property、Target 和 Task：

1
<project name="demo" default="build" basedir=".">
2
    <property name="build.dir" value="build"/>
3

4
    <target name="compile">
5
        <mkdir dir="${build.dir}/classes"/>
6
        <javac srcdir="src" destdir="${build.dir}/classes"/>
7
    </target>
8

9
    <target name="build" depends="compile">
10
        <jar destfile="${build.dir}/demo.jar"
11
             basedir="${build.dir}/classes"/>
12
    </target>
13
</project>

Ant 的特点是开发者直接描述动作：创建目录、调用编译器、复制文件、生成压缩包。depends 建立 Target 之间的先后关系，但 Ant 不会自动理解所有输入输出，也不会自动为每个任务建立现代缓存模型。

适合 Ant 的场景：

• 维护已有的 XML 构建流程。
• 需要直接调用大量历史 Ant Task。
• 构建步骤简单、团队熟悉 XML 且没有复杂依赖治理需求。

Ant 的主要维护风险：

• Target 之间的依赖容易变成隐式顺序。
• 相同路径、参数和动作可能在多个 Target 中重复。
• 构建逻辑增长后，XML 层级和 Property 覆盖关系难以追踪。
• 依赖下载、版本冲突和发布元数据通常需要额外工具配合。

3.7 Maven 的工作方式#

Maven 项目通常由 pom.xml 描述：

1
<project>
2
    <modelVersion>4.0.0</modelVersion>
3
    <groupId>com.example</groupId>
4
    <artifactId>demo</artifactId>
5
    <version>1.0.0</version>
6

7
    <properties>
8
        <maven.compiler.release>21</maven.compiler.release>
9
    </properties>
10

11
    <dependencies>
12
        <dependency>
13
            <groupId>org.junit.jupiter</groupId>
14
            <artifactId>junit-jupiter</artifactId>
15
            <version>6.0.3</version>
16
            <scope>test</scope>
17
        </dependency>
18
    </dependencies>
19
</project>

Maven 的核心是 Project Object Model（POM）和标准生命周期。用户执行 mvn package 时，Maven 会沿生命周期执行从验证、编译、测试到打包所需的阶段；插件将具体 Mojo 绑定到生命周期阶段。

Maven 的优势：

• 标准目录和生命周期约定清晰。
• POM、仓库和发布生态成熟。
• 团队成员通常可以快速理解基础项目。
• 多模块 Reactor 能够统一构建相关模块。

Maven 的边界：

• 大量非标准流程通常需要编写或组合插件。
• XML 表达复杂条件、循环和对象关系比较笨重。
• 生命周期阶段固定，特殊任务编排需要理解插件绑定和执行顺序。
• 性能优化和自定义构建模型的表达空间相对受限。

3.8 Gradle 的工作方式#

Gradle 通过 Settings、Project、Plugin 和 Task 组成构建模型：

1
plugins {
2
    java
3
}
4

5
repositories {
6
    mavenCentral()
7
}
8

9
dependencies {
10
    testImplementation("org.junit.jupiter:junit-jupiter:6.0.3")
11
}
12

13
tasks.withType<Test>().configureEach {
14
    useJUnitPlatform()
15
}

Gradle 不要求所有构建都遵循一个固定生命周期，而是由插件创建任务、任务之间建立依赖，用户请求某个生命周期任务时再计算需要执行的任务图。

这种模型带来更大的表达能力，也带来更高的设计责任：

• 要明确任务输入和输出。
• 要避免配置阶段副作用。
• 要控制跨项目隐式配置。
• 要治理插件和依赖版本。
• 要持续验证 Configuration Cache、Build Cache 和并行构建的兼容性。

3.9 生命周期对比#

不要把 Maven 的 Phase 名称机械映射成 Gradle Task 名称。例如 Maven 的 package 和 Gradle 的 build 都可能生成构件，但它们的验证范围、插件绑定和任务关系并不完全相同。迁移时应先列出实际交付目标，再映射任务和验证门禁。

3.10 依赖管理对比#

1
<dependency>
2
    <groupId>com.google.guava</groupId>
3
    <artifactId>guava</artifactId>
4
    <version>33.5.0-jre</version>
5
</dependency>

1
dependencies {
2
    implementation("com.google.guava:guava:33.5.0-jre")
3
    testImplementation("org.junit.jupiter:junit-jupiter:6.0.3")
4
}

3.11 插件和扩展机制对比#

Gradle Extension 的优势是可以将配置和实现分离：

1
companyQuality {
2
    failOnWarning.set(true)
3
    reportDirectory.set(layout.buildDirectory.dir("reports/company"))
4
}

但扩展对象越多，构建模型越复杂。插件作者应提供合理默认值、明确属性类型和错误信息，不要让消费者依赖内部 Task 名称。

3.12 多模块项目对比#

Maven 常用 Parent POM 和 <modules> 管理多模块：

1
root
2
├── pom.xml
3
├── core/pom.xml
4
└── app/pom.xml

Gradle 使用 Settings 声明项目：

1
rootProject.name = "demo"
2
include("core", "app")

Ant 通常需要自行编排多个子目录中的 Target。Gradle 和 Maven 都可以建立模块依赖，但 Gradle 还可以使用 Composite Build 将多个独立构建组合起来：

1
includeBuild("build-logic")

选择多模块方案时，重点不是目录数量，而是：

• 模块是否有稳定职责。
• 依赖方向是否清晰。
• 是否需要独立测试、发布和版本。
• 共享构建逻辑是否已经成为维护负担。
• 构建性能是否因模块数量和配置方式受到影响。

3.13 可复现性与性能对比#

无论使用哪一种工具，都应固定：

• 构建工具版本。
• JDK 和编译器版本。
• 依赖版本和仓库来源。
• 操作系统差异和环境变量。
• 生成物、报告和失败日志。

性能也不能只比较一次 clean build 的耗时。应区分首次构建、增量构建、CI 干净构建、缓存命中和依赖已下载等场景。

3.14 Maven 项目迁移到 Gradle#

迁移不应从“把 XML 翻译成 Kotlin”开始，而应从构建契约开始：

1. 列出源码目录、资源目录、测试目录和生成目录。
2. 记录所有生命周期阶段、插件 Goal 和自定义脚本。
3. 记录直接依赖、传递依赖、BOM、Profile 和仓库。
4. 记录发布的 POM、Module Metadata、sources、javadoc 和签名要求。
5. 使用 gradle init 或迁移工具生成初始结构。
6. 先让编译和测试通过，再迁移质量检查、代码生成和发布。
7. 比较迁移前后的类路径、测试结果和构件内容。
8. 删除旧构建入口前，在 CI 和干净环境中验证一段时间。

常见迁移映射：

映射表只是起点。Maven Profile 可能同时包含属性、依赖、插件和资源替换，迁移时应拆成多个职责明确的 Gradle 配置。

3.15 Ant 构建迁移到 Gradle#

Ant 迁移应先识别每个 Target 的输入、输出和真实依赖：

1
Target compile
2
├── 输入：src/**/*.java、编译参数、外部 JAR
3
├── 输出：build/classes
4
└── 后续：test、jar

再将其转换为 Gradle Task 或标准插件配置：

• javac → java 插件提供的 compileJava。
• junit → Test 任务和测试依赖。
• jar → jar 任务。
• copy → Copy 任务或 Source Set 资源配置。
• exec → 明确声明输入输出的自定义 Task。
• 公共 XML Target → Convention Plugin。

Gradle 可以调用 Ant Task 以降低迁移风险：

1
tasks.register("legacyAntStep") {
2
    doLast {
3
        ant.invokeMethod("echo", mapOf("message" to "legacy step"))
4
    }
5
}

但兼容调用应是过渡方案。长期目标应是把核心流程转换成 Gradle 原生插件、任务类型和输入输出模型。

3.16 选择决策矩阵#

最终选择应基于总拥有成本，包括学习、迁移、插件维护、CI、升级、排错和团队交接成本。

4.1 是否必须全局安装 Gradle#

运行已有项目时通常不需要全局安装 Gradle，应优先使用项目中的 Wrapper：

1
.\gradlew.bat build

1
./gradlew build

只有创建全新 Wrapper、维护特殊环境或学习 Gradle 本身时，才可能需要全局 Gradle。

4.2 Java 运行环境#

Gradle 本身运行在 JVM 上。Gradle 9.6.1 支持使用 JVM 17 至 JVM 26 运行。本文建议学习环境使用 JDK 21；真实项目应按 Gradle、框架、Android Gradle Plugin 和部署目标的兼容矩阵选择版本。

检查环境：

1
java -version
2
$env:JAVA_HOME
3
.\gradlew.bat --version

JAVA_HOME、IDE 的 Gradle JVM、Java Toolchain 和应用运行 JDK 是不同概念。排错时要确认究竟是哪一个 JVM 在工作。

4.3 常见安装方式#

可以通过 SDKMAN!、Homebrew、Scoop 或手动下载二进制包安装全局 Gradle。安装后检查：

1
gradle --version

不要因为系统中存在全局 Gradle 就跳过 Wrapper。项目构建仍应优先调用 gradlew 或 gradlew.bat。

4.4 环境准备清单#

开始使用 Gradle 前，至少确认以下条件：

• 操作系统、Shell 和工作目录明确。
• 用于启动 Gradle 的 JVM 在当前 Gradle 版本支持范围内。
• 项目是否已经包含 Wrapper。
• JAVA_HOME、IDE Gradle JVM 和 Java Toolchain 是否符合预期。
• 网络、代理、证书和私有仓库凭据可用。
• 当前用户对项目目录、Gradle User Home 和构建输出目录有读写权限。
• Windows 上的脚本执行策略、Linux/macOS 上的 Wrapper 可执行权限正常。

建议在问题出现前记录一份环境基线：

1
OS：Windows / Linux / macOS + 版本
2
Shell：PowerShell / Bash / zsh
3
Gradle：Wrapper 或全局版本
4
JDK：版本、供应商、JAVA_HOME
5
IDE：名称和 Gradle JVM
6
项目：Gradle、Kotlin、AGP 或其他插件版本
7
网络：直连、代理或私有仓库

环境信息越完整，越容易区分“构建脚本错误”和“本机环境错误”。

4.5 安装全局 Gradle 的方式#

已有项目优先使用 Wrapper；全局安装主要用于创建 Wrapper、初始化新项目或学习 Gradle 命令本身。

1
scoop install gradle

1
C:\Tools\gradle\gradle-9.6.1

1
$env:GRADLE_HOME = 'C:\Tools\gradle\gradle-9.6.1'
2
$env:Path = "$env:GRADLE_HOME\bin;$env:Path"
3
gradle --version

1
brew install gradle

1
curl -s "https://get.sdkman.io" | bash
2
sdk install gradle 9.6.1

1
curl -s "https://get.sdkman.io" | bash
2
sdk install gradle 9.6.1

4.6 验证全局安装#

Windows PowerShell：

1
Get-Command gradle
2
Get-Command java
3
java -version
4
gradle --version

Linux/macOS：

1
command -v gradle
2
command -v java
3
java -version
4
gradle --version

重点观察 gradle --version 输出中的：

• Gradle 版本。
• Gradle Launcher JVM。
• Daemon JVM。
• 操作系统和架构。
• Kotlin、Groovy、Ant 运行时版本。

如果终端中显示的 Gradle 不是预期版本，通常是 PATH 中存在多个安装目录。Windows 可使用 where.exe gradle，Linux/macOS 可使用 which -a gradle 检查所有候选路径。

4.7 四个容易混淆的 Java 环境#

Gradle 项目中至少可能出现四种 JVM：

它们可以是同一个 JDK，也可以不同。例如：

1
Gradle 用 JDK 21 启动
2
Java 编译 Toolchain 使用 JDK 17
3
应用在运行环境使用 JDK 21

排查版本错误时不要只执行 java -version。应同时检查：

1
java -version
2
.\gradlew.bat --version
3
.\gradlew.bat properties

4.8 JAVA_HOME、org.gradle.java.home 与 Toolchain#

JAVA_HOME 是操作系统和许多命令行工具默认使用的 JDK 位置：

1
$env:JAVA_HOME

org.gradle.java.home 可以在 gradle.properties 中指定 Gradle 使用的 Java Home：

1
org.gradle.java.home=C:/Program Files/Java/jdk-21

不要把机器绝对路径提交到团队公共配置中。个人环境可以放在用户级 gradle.properties，CI 应通过执行器镜像、环境变量或安全配置提供。

Java Toolchain 用于声明项目任务需要的 Java 版本：

1
java {
2
    toolchain {
3
        languageVersion = JavaLanguageVersion.of(21)
4
    }
5
}

三者的职责不同：

1
JAVA_HOME：默认启动环境
2
org.gradle.java.home：Gradle 进程的特定 JVM
3
Toolchain：项目编译、测试和运行任务的目标 JVM

4.9 Gradle User Home 与项目目录#

Gradle User Home 默认位置：

1
Windows：%USERPROFILE%\\.gradle
2
Linux/macOS：~/.gradle

可以通过环境变量修改：

1
$env:GRADLE_USER_HOME = 'D:\gradle-user-home'

1
export GRADLE_USER_HOME="$HOME/.gradle-custom"

Gradle User Home 可能包含：

• Wrapper 下载的 Gradle 分发包。
• 依赖和模块元数据缓存。
• Daemon 状态和日志。
• 用户级 gradle.properties。
• 用户级初始化脚本。
• 文件系统 watching 和构建缓存数据。

项目目录中的 .gradle/ 是项目级缓存，build/ 是项目构建输出。它们通常不应提交到版本控制：

1
.gradle/
2
build/

清理 User Home 之前应先停止 Daemon，并确认不会误删企业证书、凭据或其他工具配置：

1
.\gradlew.bat --stop

4.10 网络、代理与私有仓库#

依赖下载失败不一定是 Gradle 版本问题，常见原因包括代理、TLS 证书、DNS、仓库权限和镜像不可用。

可以在用户级或项目级 gradle.properties 中配置代理：

1
systemProp.http.proxyHost=proxy.example.com
2
systemProp.http.proxyPort=8080
3
systemProp.https.proxyHost=proxy.example.com
4
systemProp.https.proxyPort=8080

不要把代理密码和仓库密码提交到公共项目。更推荐使用环境变量、用户级属性或 CI Secret：

1
systemProp.https.proxyUser=${HTTPS_PROXY_USER}
2
systemProp.https.proxyPassword=${HTTPS_PROXY_PASSWORD}

实际使用时确认凭据注入方式符合 Gradle 和 CI 平台的属性解析规则，不要把密码直接写入日志。

网络排查顺序：

1. 用 java -version 和 gradle --version 确认环境。
2. 检查仓库 URL、代理和证书。
3. 用 dependencies --info 观察请求的仓库和失败原因。
4. 确认私有仓库凭据和访问权限。
5. 最后再使用 --refresh-dependencies 验证缓存是否过期。

4.11 Windows、Linux 与 macOS 差异#

1
chmod +x gradlew
2
./gradlew --version

4.12 IDE 中的 Gradle 环境#

IDE 可能有独立的 Gradle JVM 配置，不一定等于终端中的 JAVA_HOME。出现“终端能构建、IDE 不能构建”时检查：

• IDE 使用的是 Wrapper 还是本机 Gradle。
• IDE Gradle JVM 的版本和路径。
• IDE 是否覆盖了项目的 gradle.properties。
• IDE 使用的代理、证书和凭据是否不同。
• 项目同步失败是配置阶段问题，还是任务执行问题。

建议先用命令行 Wrapper 验证：

1
.\gradlew.bat help
2
.\gradlew.bat tasks

如果命令行成功而 IDE 失败，优先检查 IDE 的 Gradle 设置；如果两者都失败，再检查项目脚本、插件和依赖。

4.13 CI 中的环境准备#

CI 不应依赖执行器预装的全局 Gradle。推荐流程：

1
检出代码
2
  ↓
3
准备明确版本的 JDK
4
  ↓
5
调用项目 Wrapper
6
  ↓
7
恢复安全缓存
8
  ↓
9
执行 check/build
10
  ↓
11
保存测试报告和构建产物

CI 环境至少要明确：

• JDK 发行版和版本。
• 操作系统架构。
• Wrapper 分发包来源和校验。
• Gradle User Home 缓存位置。
• 私有仓库、代理和证书。
• 发布凭据是否只在受保护任务中可用。

5.1 Wrapper 文件#

1
gradle/
2
└── wrapper/
3
    ├── gradle-wrapper.jar
4
    └── gradle-wrapper.properties
5
gradlew
6
gradlew.bat

这些文件通常都应提交到版本控制。

5.2 Wrapper 的价值#

• 团队成员使用同一个 Gradle 版本。
• CI 不需要预装特定 Gradle。
• 升级记录进入版本控制。
• 减少“我的机器可以构建”的环境差异。

5.3 生成和使用 Wrapper#

1
gradle wrapper --gradle-version 9.6.1 --distribution-type all

Windows PowerShell：

1
.\gradlew.bat tasks
2
.\gradlew.bat build

Linux/macOS：

1
./gradlew tasks
2
./gradlew build

all 分发包包含二进制、源码和文档，IDE 体验更完整；CI 若只追求体积可考虑 bin。

5.4 Wrapper 配置#

gradle/wrapper/gradle-wrapper.properties 示例：

1
distributionBase=GRADLE_USER_HOME
2
distributionPath=wrapper/dists
3
distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-all.zip
4
networkTimeout=10000
5
validateDistributionUrl=true
6
zipStoreBase=GRADLE_USER_HOME
7
zipStorePath=wrapper/dists

5.5 升级 Wrapper#

1
.\gradlew.bat wrapper --gradle-version 9.6.1 --distribution-type all
2
.\gradlew.bat wrapper
3
.\gradlew.bat --version
4
.\gradlew.bat help --warning-mode all
5
.\gradlew.bat build

再次运行 Wrapper 任务，可以使启动脚本、Wrapper JAR 和属性文件都由目标版本生成。

5.6 Wrapper 安全#

• 不随意接受来源不明的 gradle-wrapper.jar。
• 审查 distributionUrl 是否指向可信来源。
• 使用 distributionSha256Sum 固定分发包校验值。
• 代码审查中关注 Wrapper 版本变化。
• CI 中避免对不可信分支授予发布凭据或高权限。

5.7 Wrapper 的执行链路#

执行：

1
.\gradlew.bat build

可以抽象为以下过程：

1
gradlew.bat / gradlew
2
        ↓
3
读取 gradle-wrapper.properties
4
        ↓
5
定位 GRADLE_USER_HOME
6
        ↓
7
检查目标 Gradle 分发包是否已缓存
8
        ↓
9
必要时下载并校验分发包
10
        ↓
11
启动指定版本的 Gradle
12
        ↓
13
执行 build 任务

Wrapper 并不是把 Gradle 完整复制进 Git 仓库，而是提交启动代码、配置和 Wrapper JAR；实际 Gradle 分发包通常下载到用户级缓存目录。这样可以保持仓库体积较小，并让不同项目使用不同 Gradle 版本。

5.8 Wrapper 文件职责#

不要只提交 gradlew 而遗漏 gradle-wrapper.jar 或 gradle-wrapper.properties。不同操作系统的启动脚本也应一起提交，否则 CI 或团队成员可能无法直接构建。

5.9 bin 与 all 分发包#

Wrapper 的 distributionUrl 通常指向两种分发包之一：

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

1
distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-all.zip

• bin：包含运行 Gradle 所需的二进制内容，体积较小，适合 CI 和一般构建。
• all：包含二进制、源码和文档，适合需要 IDE 源码导航或离线查阅的开发环境。

两者应保持版本号一致。不要在同一个项目的不同分支中随意切换分发类型，否则可能导致本地缓存、IDE 行为和构建时间差异。

5.10 gradle-wrapper.properties 详解#

1
distributionBase=GRADLE_USER_HOME
2
distributionPath=wrapper/dists
3
distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zip
4
distributionSha256Sum=<官方 SHA-256>
5
networkTimeout=10000
6
retries=3
7
retryBackOffMs=1000
8
validateDistributionUrl=true
9
zipStoreBase=GRADLE_USER_HOME
10
zipStorePath=wrapper/dists

主要属性：

• distributionUrl：Gradle 分发包地址，是最重要的版本来源。
• distributionSha256Sum：可选的分发包 SHA-256 校验值，用于防止下载内容被替换或损坏。
• distributionBase、distributionPath：分发包解压目录的基础位置和相对路径。
• zipStoreBase、zipStorePath：下载 ZIP 文件的缓存位置。
• networkTimeout：网络操作超时时间，单位为毫秒。
• retries：下载失败时的重试次数。
• retryBackOffMs：重试之间的等待时间。
• validateDistributionUrl：是否对分发 URL 做额外校验。

属性名称和可用行为应以当前 Wrapper 版本的官方文档为准。不要把凭据直接拼接进 URL，例如不要提交 https://user:password@example.com/...。

5.11 生成 Wrapper 的推荐方式#

在已有全局 Gradle 的目录中生成：

1
gradle wrapper --gradle-version 9.6.1 --distribution-type bin

需要源码和文档时：

1
gradle wrapper --gradle-version 9.6.1 --distribution-type all

如果项目已经有 Wrapper，优先使用当前 Wrapper 执行升级任务：

1
.\gradlew.bat wrapper --gradle-version 9.6.1 --distribution-type bin

推荐使用完整的 major.minor.patch 版本，而不是动态版本或只写大版本。这样可以让本地、CI 和未来重建使用相同的分发包。

5.12 Wrapper 升级流程#

升级 Wrapper 不等于只修改一行 URL。建议按以下流程执行：

1. 阅读目标 Gradle 版本的 Release Notes 和升级说明。
2. 核对运行 JVM、Kotlin、Android Gradle Plugin 和第三方插件兼容性。
3. 在独立分支运行 Wrapper 升级任务。
4. 检查 gradlew、gradlew.bat、Wrapper JAR 和属性文件的差异。
5. 第二次运行 Wrapper 任务，使 Wrapper 脚本和 JAR 由目标版本生成。
6. 验证 --version、help、tasks、check 和 build。
7. 对比依赖树、测试报告、构件和构建耗时。
8. 在干净 CI 环境中重新验证。

示例：

1
.\gradlew.bat wrapper --gradle-version 9.6.1 --distribution-type bin
2
.\gradlew.bat wrapper
3
.\gradlew.bat --version
4
.\gradlew.bat help --warning-mode all
5
.\gradlew.bat check
6
.\gradlew.bat build

升级提交应保持小而可回滚，不要把 Wrapper 升级和业务代码重构混在一个提交中。

5.13 分发包校验#

可以在 Wrapper 属性中保存官方校验和：

1
distributionSha256Sum=<官方 SHA-256>

也可以在生成 Wrapper 时传入：

1
gradle wrapper `
2
    --gradle-version 9.6.1 `
3
    --gradle-distribution-sha256-sum <官方 SHA-256>

校验值应从可信的 Gradle 官方发布信息获得，并在代码审查中核对版本、文件名和校验值是否一一对应。

校验解决的是“下载的 Gradle 分发包是否是预期内容”，不能替代：

• Wrapper JAR 的来源审查。
• 构建脚本和插件代码审查。
• 依赖的 Dependency Verification。
• CI 权限和 Secret 管理。
• 生成构件的签名和发布验证。

5.14 Wrapper JAR 验证#

gradle-wrapper.jar 会参与构建启动，应该像源代码一样接受审查。团队可以在 CI 中验证 Wrapper JAR 是否来自可信版本和来源。

建议检查：

• Wrapper JAR 是否是项目升级产生的预期变更。
• 文件是否被意外替换或注入额外内容。
• distributionUrl 是否指向允许的域名。
• Wrapper 校验工作流是否在 Pull Request 中执行。
• 依赖和构建脚本是否来自可信分支。

不要从随机博客、Issue 附件或不明项目复制 Wrapper JAR。若历史项目的 Wrapper 文件来源不明，应先在隔离环境中重新生成并审查差异。

5.15 企业内网和私有分发地址#

企业可以把 Gradle 分发包放在内部镜像或制品仓库：

1
distributionUrl=https\://packages.example.com/gradle/gradle-9.6.1-bin.zip

此时需要明确：

• 地址是否对开发机和 CI 都可访问。
• TLS 证书是否被所有构建节点信任。
• 分发包是否经过内部校验和审批。
• 镜像是否保留官方文件名和版本关系。
• 是否需要身份认证，以及凭据如何安全注入。
• 离线构建和灾备环境是否有可用副本。

不要通过提交用户名和密码解决私服访问问题。应使用企业代理、机器身份、短期令牌或 CI Secret，并限制读取权限。

5.16 CI 中的 Wrapper 规范#

CI 脚本应直接调用项目 Wrapper：

1
- name: Verify Gradle
2
  run: ./gradlew --version
3

4
- name: Run checks
5
  run: ./gradlew check --no-daemon

推荐的 CI 门禁：

• 验证 Wrapper JAR。
• 验证 distributionUrl 和分发包校验值。
• 禁止构建脚本自动下载未经批准的第三方 Gradle 分发包。
• 缓存 Gradle User Home 时隔离可信和不可信构建。
• 发布任务只在受保护分支或签名标签中执行。
• 保存 Wrapper 升级、构建失败和分发下载日志。

6.1 使用 gradle init#

创建 Java 应用：

1
mkdir gradle-demo
2
cd gradle-demo
3
gradle init --type java-application --dsl kotlin --test-framework junit-jupiter --java-version 21 --project-name gradle-demo

也可以执行交互式初始化：

1
gradle init

初始化后使用 Wrapper：

1
.\gradlew.bat build
2
.\gradlew.bat run

6.2 常见项目类型#

gradle init 可生成的模板会随版本变化，常见类型包括：

• Basic Build。
• Application。
• Library。
• Gradle Plugin。
• 从 Maven 构建迁移。

查看当前版本支持的选项：

1
gradle help --task init

6.3 推荐初始化选择#

对普通 JVM 新项目：

• DSL：Kotlin。
• 测试：JUnit Jupiter。
• Java：由 Toolchain 明确指定。
• 多模块：业务复杂度确实需要时再拆分。
• 包名：使用稳定的反向域名命名空间。

6.4 初始化前的准备#

gradle init 会根据当前目录、命令行参数和交互式选择生成构建文件。执行前先确定：

• 项目是 Application、Library、Basic Build 还是 Gradle Plugin。
• 使用 Kotlin DSL 还是 Groovy DSL。
• 使用哪个测试框架。
• Java 项目的 Toolchain 或目标语言版本。
• 包名、项目名、Group 和初始版本。
• 是否生成拆分的多项目结构。
• 当前目录是否为空，以及是否允许覆盖已有文件。

新项目推荐在一个新的目录中初始化：

1
mkdir gradle-demo
2
Set-Location gradle-demo
3
gradle init

不要直接在含有重要源码、配置或脚本的目录中执行初始化。先使用版本控制或备份确认变更范围。

6.5 gradle init 的常用参数#

查看当前版本支持的完整参数：

1
gradle help --task init

常见参数：

参数的可用范围会随 Gradle 版本变化。以 gradle help --task init 的输出为准，不要把其他版本的命令行参数直接复制到当前项目。

6.6 常见项目模板#

不是所有模板在所有版本中都默认出现。模板列表、参数名称和生成内容应通过 gradle init 的交互提示或 help --task init 确认。

6.7 非交互式初始化#

适合脚本、模板仓库和 CI 的初始化命令应显式提供关键参数：

1
gradle init \
2
  --type java-application \
3
  --dsl kotlin \
4
  --test-framework junit-jupiter \
5
  --java-version 21 \
6
  --project-name hello-gradle \
7
  --package com.example.app \
8
  --use-defaults

Windows PowerShell：

1
gradle init `
2
  --type java-application `
3
  --dsl kotlin `
4
  --test-framework junit-jupiter `
5
  --java-version 21 `
6
  --project-name hello-gradle `
7
  --package com.example.app `
8
  --use-defaults

在团队脚本中，建议把完整命令和生成后的文件一起提交或记录。不要依赖交互式输入顺序，因为不同 Gradle 版本可能增加或调整问题。

6.8 生成文件后的检查#

初始化成功后，先不要立即改业务代码，先检查生成结果：

1
Get-ChildItem -Force
2
Get-ChildItem -Recurse -File | Select-Object FullName

重点查看：

• settings.gradle.kts 是否包含正确的 rootProject.name。
• build.gradle.kts 是否应用预期插件。
• 源码包名与目录路径是否一致。
• src/main 和 src/test 是否符合项目类型。
• gradle/wrapper、gradlew 和 gradlew.bat 是否生成。
• 是否错误地生成了不需要的示例资源或注释。
• gradle.properties 是否包含了不应提交的本机配置。

随后运行：

1
.\gradlew.bat --version
2
.\gradlew.bat projects
3
.\gradlew.bat tasks --all
4
.\gradlew.bat test
5
.\gradlew.bat build

6.9 Application、Library 和 Basic Build 的选择#

1
plugins {
2
    application
3
}
4

5
application {
6
    mainClass = "com.example.App"
7
}

1
plugins {
2
    `java-library`
3
}

6.10 Kotlin DSL、Groovy DSL 与测试框架选择#

新项目通常可以选择：

1
Kotlin DSL + JUnit Jupiter + Java Toolchain

选择依据：

• 团队已经大量使用 Kotlin：Kotlin DSL 更容易复用语言经验。
• 团队维护大量 Groovy 构建脚本：继续 Groovy DSL 可能迁移成本更低。
• 新 Java/JVM 项目：JUnit Jupiter 是常见默认选择，但应遵循团队测试规范。
• 需要兼容既有 TestNG 测试：选择 TestNG 或逐步迁移测试框架。
• 需要 Spock：确认 Groovy、Spock 和 Gradle Plugin 版本兼容。

初始化时选择的 DSL 不是永久承诺。可以迁移，但要同时处理插件访问器、Provider API、闭包语义、脚本导入和自定义插件。

6.11 包名、项目名与坐标#

初始化时需要区分几个名称：

包名应保持稳定，避免把公司内部临时域名、用户名或机器路径写进公共 API。项目目录名可以改变，但发布坐标和源码包名一旦被消费者使用，修改成本会显著增加。

6.12 从 Maven 项目初始化或转换#

对于已有 Maven 项目，可以让 Gradle Init Plugin 根据 pom.xml 生成初始 Gradle 文件：

1
gradle init --type pom

也可以在 Maven 项目目录中直接执行交互式初始化，让 Gradle 读取现有 POM。

转换结果只能作为迁移起点，应人工检查：

• Maven Profile 是否被正确表达。
• Plugin Execution 和 Goal 是否映射。
• provided、runtime、test Scope 是否转换为正确 Configuration。
• Parent POM、BOM 和 Dependency Management 是否保留。
• 资源过滤、代码生成、签名和发布配置是否完整。
• Maven 和 Gradle 构建出的类路径与构件是否一致。

迁移完成前，不要删除原始 pom.xml 或停止原 CI 流程。

6.13 初始化后建立 Wrapper#

gradle init 通常会生成 Wrapper。确认文件存在：

1
Test-Path .\gradlew.bat
2
Test-Path .\gradlew
3
Test-Path .\gradle\wrapper\gradle-wrapper.jar
4
Test-Path .\gradle\wrapper\gradle-wrapper.properties

如果模板或历史项目没有生成 Wrapper，可以补充：

1
gradle wrapper --gradle-version 9.6.1 --distribution-type bin
2
.\gradlew.bat --version

生成 Wrapper 后，后续命令统一改用 gradlew 或 gradlew.bat，不要继续混用全局 Gradle。

6.14 初始化后的 Git 提交边界#

第一次提交可以包含：

• settings.gradle.kts 或 settings.gradle。
• build.gradle.kts 或 build.gradle。
• Wrapper 文件。
• src/ 下的最小源码和测试。
• gradle.properties 中不含敏感信息的公共配置。
• .gitignore。
• README 和构建命令说明。

不应提交：

• .gradle/。
• build/。
• 用户目录和机器绝对路径。
• 本地密钥、密码、Token。
• IDE 私有配置，除非团队明确约定。
• 临时下载包和未审查的生成物。

建议初始化后先提交一个“可构建基线”，再逐步添加依赖、插件和业务代码。这样后续问题更容易定位到具体变更。

7.1 settings.gradle.kts#

1
pluginManagement {
2
    repositories {
3
        gradlePluginPortal()
4
        mavenCentral()
5
    }
6
}
7

8
dependencyResolutionManagement {
9
    repositories {
10
        mavenCentral()
11
    }
12
}
13

14
rootProject.name = "gradle-demo"

多项目构建还会声明：

1
include("app", "core", "service")

7.2 build.gradle.kts#

1
plugins {
2
    application
3
}
4

5
java {
6
    toolchain {
7
        languageVersion = JavaLanguageVersion.of(21)
8
    }
9
}
10

11
repositories {
12
    mavenCentral()
13
}
14

15
dependencies {
16
    testImplementation("org.junit.jupiter:junit-jupiter:6.0.3")
17
}
18

19
application {
20
    mainClass = "com.example.App"
21
}
22

23
tasks.test {
24
    useJUnitPlatform()
25
}

7.3 gradle.properties#

适合配置构建行为：

1
org.gradle.caching=true
2
org.gradle.configuration-cache=true
3
org.gradle.parallel=true
4
org.gradle.warning.mode=all

不要把密码、Token、私钥直接提交到项目中的 gradle.properties。

7.4 local.properties#

local.properties 常见于 Android 项目，用于保存 Android SDK 等机器本地路径。它不是所有 Gradle 项目的标准必需文件，通常不应提交。

7.5 Gradle User Home#

默认目录：

1
Windows: %USERPROFILE%\.gradle
2
Linux/macOS: ~/.gradle

它可能包含下载的 Gradle 分发包、依赖缓存、Daemon 日志、用户级属性和初始化脚本。可通过 GRADLE_USER_HOME 修改位置。

7.6 根项目与子项目目录#

单项目构建通常是：

1
project/
2
├── settings.gradle.kts
3
├── build.gradle.kts
4
├── gradle/
5
├── src/
6
└── gradlew

多项目构建通常是：

1
project/
2
├── settings.gradle.kts
3
├── build.gradle.kts
4
├── gradle/
5
├── app/
6
│   ├── build.gradle.kts
7
│   └── src/
8
├── core/
9
│   ├── build.gradle.kts
10
│   └── src/
11
└── service/
12
    ├── build.gradle.kts
13
    └── src/

根项目通常负责整个 Build 的入口、聚合任务、插件版本、仓库策略和公共构建逻辑；子项目负责自身的插件、源码、依赖、测试和发布配置。

不要因为根目录有 build.gradle.kts 就把所有模块配置都塞到根脚本。根项目可以是聚合项目，也可以有自己的源码；二者应根据项目职责明确区分。

7.7 settings.gradle(.kts) 的职责#

Settings 文件是一次 Gradle Build 的入口，主要负责：

• 设置 rootProject.name。
• 使用 include 声明子项目。
• 配置 pluginManagement。
• 配置 dependencyResolutionManagement。
• 创建或导入 Version Catalog。
• 引入 Included Build 和构建逻辑。
• 配置 Build Cache 或全局构建服务。
• 定义项目目录与项目路径的映射。

示例：

1
pluginManagement {
2
    repositories {
3
        gradlePluginPortal()
4
        mavenCentral()
5
    }
6
}
7

8
dependencyResolutionManagement {
9
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
10
    repositories {
11
        mavenCentral()
12
    }
13
}
14

15
rootProject.name = "company-platform"
16
include(":app", ":core", ":service")
17
includeBuild("build-logic")

Settings 不适合承载某个模块的业务编译逻辑，也不应直接执行编译、测试或发布动作。它的重点是定义“这个 Build 包含什么以及如何解析”。

7.8 项目路径与目录映射#

默认情况下，项目路径和目录结构一致：

1
include(":app", ":core")

对应：

1
:app  → app/
2
:core → core/

如果目录名称和项目路径不同，可以显式指定：

1
include(":frontend")
2
project(":frontend").projectDir = file("web-client")

多项目中应尽量保持项目路径、目录名称和模块职责一致。只有迁移旧仓库或兼容既有目录时，才使用复杂映射。

7.9 build.gradle(.kts) 的结构#

一个可读的构建脚本通常按以下顺序组织：

1
plugins {
2
    application
3
}
4

5
group = "com.example"
6
version = "1.0.0"
7

8
java {
9
    toolchain {
10
        languageVersion = JavaLanguageVersion.of(21)
11
    }
12
}
13

14
repositories {
15
    mavenCentral()
16
}
17

18
dependencies {
19
    implementation("com.google.guava:guava:33.5.0-jre")
20
    testImplementation("org.junit.jupiter:junit-jupiter:6.0.3")
21
}
22

23
application {
24
    mainClass = "com.example.App"
25
}
26

27
tasks.withType<Test>().configureEach {
28
    useJUnitPlatform()
29
}

建议的阅读顺序是：插件 → 项目元数据 → Toolchain → 仓库 → 依赖 → 插件 Extension → Task 配置 → 自定义逻辑。

上面的 group 前不应有多余缩进，正确写法是：

1
group = "com.example"

构建脚本应保持短小。如果一个模块的脚本需要大量条件、循环、文件扫描和跨项目修改，应考虑提取 Convention Plugin。

7.10 gradle.properties 的作用和优先级#

gradle.properties 可以配置 Gradle 行为和项目属性：

1
org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
2
org.gradle.caching=true
3
org.gradle.configuration-cache=true
4
org.gradle.parallel=true

常见位置和优先级应以当前 Gradle 文档为准，通常需要区分：

1
命令行参数
2
    ↓
3
系统属性和项目级 gradle.properties
4
    ↓
5
Gradle User Home 中的 gradle.properties
6
    ↓
7
环境变量

项目级文件适合放团队共同认可的构建行为；用户级文件适合放本机路径、私有仓库凭据和个人默认参数。不要将机器绝对路径和敏感信息放入项目级文件。

区分三类属性：

• -Pname=value：项目属性，通常供构建脚本读取。
• -Dname=value：系统属性，传给 Gradle JVM 或构建环境。
• org.gradle.*：Gradle 自身的构建行为属性。

例如：

1
.\gradlew.bat build -PreleaseVersion=1.2.0
2
.\gradlew.bat build -Dorg.gradle.logging.level=info

7.11 Init Script 与项目配置的区别#

Init Script 位于 Gradle User Home 或通过 -I 参数指定，在 Settings 和项目脚本之前执行。它可以用于企业级仓库镜像、统一监听器或机器级配置，但会影响多个 Build：

1
.\gradlew.bat build --init-script .\company.init.gradle.kts

常见位置：

1
GRADLE_USER_HOME/init.gradle(.kts)
2
GRADLE_USER_HOME/init.d/*.init.gradle(.kts)
3
GRADLE_HOME/init.d/*.init.gradle(.kts)

Init Script 的问题在于它不一定在代码仓库中可见。出现“本机能构建、CI 不能构建”或“同一项目不同用户行为不同”时，应检查用户级 Init Script。

企业可以使用 Init Script 提供镜像或通用规则，但应把它们像生产代码一样版本化、审查和记录。

7.12 Source Set 的目录结构#

Java 插件默认提供 main 和 test 两个 Source Set：

1
src/main/java/        # 生产 Java 源码
2
src/main/resources/   # 生产资源
3
src/test/java/        # 测试 Java 源码
4
src/test/resources/   # 测试资源

Source Set 不只是目录，它还关联：

• 源文件集合。
• 资源文件集合。
• 编译类路径。
• 运行时类路径。
• 编译输出目录。
• 依赖 Configuration。
• 对应的编译、资源处理和测试任务。

因此，将文件放入某个目录会影响任务输入和类路径，但不会自动创建所有业务语义。自定义 Source Set 时，需要同时配置依赖、任务和生命周期关系。

7.13 自定义 Source Set#

例如创建集成测试 Source Set：

1
val integrationTest by sourceSets.creating
2

3
configurations[integrationTest.implementationConfigurationName]
4
    .extendsFrom(configurations.testImplementation.get())
5

6
val integrationTestTask = tasks.register<Test>("integrationTest") {
7
    description = "运行集成测试"
8
    group = "verification"
9
    testClassesDirs = integrationTest.output.classesDirs
10
    classpath = integrationTest.runtimeClasspath
11
    shouldRunAfter(tasks.test)
12
}
13

14
tasks.named("check") {
15
    dependsOn(integrationTestTask)
16
}

还需要创建对应目录：

1
src/integrationTest/java/
2
src/integrationTest/resources/

自定义 Source Set 之前，先确认是否可以使用现有插件提供的测试变体或任务。自行创建过多 Source Set 会增加配置、类路径和 CI 维护成本。

7.14 资源、生成源码与构建输出#

应区分三类文件：

1
手写源码和资源
2
    src/main/
3

4
构建过程中生成的源码和资源
5
    build/generated/
6

7
编译、测试、打包和报告输出
8
    build/classes/
9
    build/resources/
10
    build/reports/
11
    build/libs/

生成源码不应写回 src/main/java，否则会污染版本控制、导致重复编译和 IDE 同步问题。推荐：

1
val generatedDir = layout.buildDirectory.dir("generated/sources/demo/main")
2

3
sourceSets {
4
    main {
5
        java.srcDir(generatedDir)
6
    }
7
}

生成任务必须声明输出目录，并让编译任务通过 Provider 或任务依赖消费该目录。

7.15 build/、.gradle/ 与 Gradle User Home#

这三个位置容易混淆：

推荐 .gitignore：

1
.gradle/
2
build/
3
!gradle/wrapper/gradle-wrapper.jar
4
!gradle/wrapper/gradle-wrapper.properties

不要使用 git add . 之后再想办法排除构建缓存。先建立正确的 .gitignore，再提交源码和构建契约。

7.16 Android 项目目录差异#

Android 项目仍使用 Settings、Build Script、Gradle User Home 和 Wrapper，但 Source Set 和输出目录由 Android Gradle Plugin 扩展：

1
android-project/
2
├── settings.gradle.kts
3
├── build.gradle.kts
4
├── gradle.properties
5
├── gradle/
6
├── app/
7
│   ├── build.gradle.kts
8
│   └── src/
9
│       ├── main/
10
│       ├── debug/
11
│       ├── release/
12
│       ├── test/
13
│       └── androidTest/
14
├── local.properties
15
└── gradlew.bat

local.properties 通常记录本机 Android SDK 路径，不应提交。src/debug、src/release、Flavor 和组合 Variant 的优先级由 AGP 决定，不能只按普通 Java Source Set 的直觉理解。

7.17 目录和文件命名规范#

推荐：

• 项目目录使用小写、短横线或团队统一命名。
• 子项目目录与项目路径保持一致。
• Kotlin DSL 文件统一使用 .gradle.kts。
• 构建逻辑放在 build-logic/ 或约定目录，不与业务源码混放。
• 生成输出统一放在 build/ 下。
• 报告按工具和任务区分目录。
• 公共版本目录放在 gradle/libs.versions.toml。

避免：

• 使用 src 目录同时存放手写源码和生成源码。
• 在多个位置复制同一份仓库或 JDK 配置。
• 用 local.properties 保存团队共享设置。
• 用随机目录名或机器用户名作为项目身份。
• 将下载的外部 JAR 放进 libs/ 后长期不治理。

7.18 观察项目结构的命令#

1
.\gradlew.bat projects
2
.\gradlew.bat tasks --all
3
.\gradlew.bat properties
4
.\gradlew.bat buildEnvironment
5
.\gradlew.bat dependencies

PowerShell 查看文件树：

1
Get-ChildItem -Force
2
Get-ChildItem -Recurse -File | Select-Object FullName

Linux/macOS：

1
find . -maxdepth 3 -type f | sort
2
./gradlew projects
3
./gradlew tasks --all
4
./gradlew properties

这些命令可以帮助确认：项目是否被 Settings 包含、插件是否生效、属性是否加载、任务是否生成以及依赖从哪里来。

8.1 文件名#

8.2 Kotlin DSL 示例#

1
plugins {
2
    java
3
}
4

5
dependencies {
6
    implementation("com.google.guava:guava:33.5.0-jre")
7
}
8

9
tasks.register("hello") {
10
    doLast {
11
        println("Hello Gradle")
12
    }
13
}

8.3 Groovy DSL 示例#

1
plugins {
2
    id 'java'
3
}
4

5
dependencies {
6
    implementation 'com.google.guava:guava:33.5.0-jre'
7
}
8

9
tasks.register('hello') {
10
    doLast {
11
        println 'Hello Gradle'
12
    }
13
}

8.4 如何选择#

新项目通常优先 Kotlin DSL，因为它的静态类型检查、IDE 补全和重构体验更好。维护现有 Groovy DSL 项目时不必为了统一而立即迁移；迁移会涉及类型、闭包、扩展访问器和插件 API 差异，应分阶段完成并持续验证。

8.5 Kotlin DSL 常见注意点#

• 字符串通常使用双引号。
• 插件短名可以写成 java、application。
• 带连字符的核心插件使用反引号，例如 `java-library`。
• 属性常用赋值语法或 Provider API，而不是 Groovy 的动态调用。
• 不要把普通 Kotlin 应用代码习惯机械套进构建脚本。

8.6 两种 DSL 共享同一个 Gradle 模型#

Kotlin DSL 和 Groovy DSL 只是表达 Gradle 模型的两种语言入口。无论使用哪一种 DSL，最终配置的仍然是同一套对象：

1
Kotlin DSL / Groovy DSL
2
          ↓
3
Settings、Project、Plugin、Extension、Configuration、Task
4
          ↓
5
相同的任务图、依赖解析和构建输出

因此，DSL 迁移不应该改变项目的构建契约。迁移前后应比较：

• 应用的插件和插件版本。
• 仓库和依赖声明。
• Task 名称、输入输出和依赖关系。
• 编译参数、测试框架和 Toolchain。
• 发布构件、POM、Module Metadata 和报告。

如果迁移后只是“脚本能编译”，但任务图、类路径或发布物发生了非预期变化，迁移仍未完成。

8.7 Kotlin DSL 的类型安全访问器#

Kotlin DSL 会根据已应用的插件和模型生成类型安全访问器：

1
plugins {
2
    java
3
    application
4
}
5

6
java {
7
    toolchain {
8
        languageVersion = JavaLanguageVersion.of(21)
9
    }
10
}
11

12
application {
13
    mainClass = "com.example.App"
14
}