Gradle注意事项

大约 2 分钟约 734 字

Gradle版本升级

Gradle版本在项目中通过Wrapper机制进行管理，配置文件路径为：

$项目根目录/gradle/wrapper/gradle-wrapper.properties

标准的配置文件内容如下：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://jv-yunwei.oss-cn-hangzhou.aliyuncs.com/gradle/gradle-8.14.3-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

提示

我们使用内网地址 https://jv-yunwei.oss-cn-hangzhou.aliyuncs.com/gradle/ 来加速Gradle的下载，避免网络问题导致的构建失败。

执行升级命令

使用以下命令升级到指定版本：

# 升级到如8.14.3
./gradlew wrapper --gradle-version=8.14.3 --gradle-distribution-url=https://jv-yunwei.oss-cn-hangzhou.aliyuncs.com/gradle/gradle-8.14.3-bin.zip

回滚操作

如果升级后出现问题，可以快速回滚使用命令或者直接撤销git变更：

# 回滚到之前的版本（例如8.5）
./gradlew wrapper --gradle-version=8.14.2 --gradle-distribution-url=https://jv-yunwei.oss-cn-hangzhou.aliyuncs.com/gradle/gradle-8.14.2-bin.zip

Configuration Cache 注意事项

注意

从 Gradle 9.0 开始，Configuration Cache 已成为稳定功能,并且新初始化的项目默认开启。在 gradle.properties 中启用 org.gradle.configuration-cache=true 后，需要特别注意代码生成工具的兼容性问题。

什么是 Configuration Cache?

Configuration Cache 是 Gradle 的一个性能优化功能，它缓存了项目配置阶段的结果。启用后，Gradle 可以跳过配置阶段，直接进入执行阶段，从而加快构建速度。

启用方式

在 gradle.properties 中添加：

org.gradle.configuration-cache=true
# 以下顺带配置 显式查看更有助于理解
org.gradle.parallel=true
org.gradle.caching=true

常见问题

1. Jimmer DTO 文件刷新问题

问题描述：

使用 Jimmer ORM 的 .dto 文件时，修改 src/main/dto 目录下的文件后，KSP 没有重新生成代码，而是使用了缓存

提示

请排除IDEA插件的影响，卸载或禁用

原因：

.dto 文件位于 src/main/dto 目录，不在标准的 Kotlin 源码路径 (src/main/kotlin) 中
Configuration Cache 模式下，Gradle 的任务输入追踪可能不会自动监控这个非标准目录

解决方案：

在 build.gradle.kts 中显式配置 KSP 任务的输入：

// oplog-service/build.gradle.kts

tasks.matching { it.name.startsWith("ksp") }.configureEach {
    inputs.dir("src/main/dto")
        .withPropertyName("dtoFiles")
        .withPathSensitivity(PathSensitivity.RELATIVE)
}

工作原理：

✅ 当 src/main/dto 目录下的文件被修改时，Gradle 检测到 inputs 变化
✅ KSP 任务被标记为 OUT-OF-DATE，重新执行并生成代码
✅ 当没有文件修改时，KSP 任务标记为 UP-TO-DATE，使用缓存，提高构建速度

验证方法：

# 1. 清理构建
./gradlew clean

# 2. 首次构建
./gradlew build --info | grep -i kspKotlin

# 3. 修改 src/main/dto 下的任意 .dto 文件
# 例如: 添加一个新字段或注释
# 显示 kspKotlin

# 4. 再次构建，观察 KSP 任务是否重新执行
./gradlew build --info | grep -i kspKotlin

# 显示 kspKotlin UP-TO-DATE

# 也可以查看 build 目录下的 ksp相关文件夹