Renovate 的 Java 依赖自动化更新实战指南：Gradle、Maven、Gradle Wrapper 与私有仓库认证-开发者社区

Renovate 的 Java 依赖自动化更新实战指南：Gradle、Maven、Gradle Wrapper 与私有仓库认证

【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate

Renovate 是跨平台依赖自动化更新工具，本文聚焦其 Java 生态支持：如何更新 Gradle、Maven 与 Ant 项目中的依赖库、插件以及 Gradle Wrapper，如何利用 LTS 版本约束避免升级到非长期支持版本，以及如何对接 Artifactory、Google Artifact Registry 等私有仓库并完成认证。读完本文，你将掌握 Renovate 在 Java 项目中的完整配置思路，并理解这些能力背后的源码实现。

概览：Renovate 如何更新 Java 依赖

Renovate 可以更新 Gradle、Maven 和 Ant 三类构建体系下的依赖，涵盖依赖库、插件以及 Gradle Wrapper 本身。从仓库的模块结构看，Java 相关支持分布在三个 manager 中：

gradlemanager：lib/modules/manager/gradle/index.ts 负责解析*.gradle/*.gradle.kts等构建脚本；
mavenmanager：lib/modules/manager/maven/index.ts 负责解析pom.xml；
gradle-wrappermanager：lib/modules/manager/gradle-wrapper/index.ts 负责 Gradle Wrapper 自身版本的升级。

一个值得注意的细节是，gradlemanager 的supportedDatasources只包含maven数据源（见 lib/modules/manager/gradle/index.ts），这说明 Gradle 与 Maven 的版本解析都经由 Maven 仓库生态完成，二者在依赖解析层面天然打通。而mavenmanager 的supportedDatasources则同时包含maven与docker，用于支持 Spring Boot OCI 打包等场景中的镜像引用。

Java LTS 版本限制：workarounds:javaLTSVersions

官方推荐的config:recommendedpreset 默认内置了workarounds:javaLTSVersionspreset，其作用是把 Java 运行时（JDK/JRE）的升级范围限制在 LTS 长期支持版本内，避免 Renovate 把项目升级到短期支持版本。

如果你希望 Renovate 提供所有major版本的 Java 升级，而不是仅限 LTS，可以在配置中把该 preset 加入ignorePresets数组：

{ "extends": ["config:recommended"], "ignorePresets": ["workarounds:javaLTSVersions"] }

源码视角：该 preset 究竟做了什么

从 lib/config/presets/internal/workarounds.preset.ts 可以清楚地看到该 preset 的实现。它以allowedVersions正则/^(?:8|11|17|21|25)(?:\.|-|$)/将允许的版本锁定在 8、11、17、21、25 这几个 LTS 主版本，并作用于docker与java-version两个数据源：

匹配的包名包括eclipse-temurin、amazoncorretto、adoptopenjdk、openjdk、java、java-jdk、java-jre、sapmachine，以及azul/zulu-openjdk、bellsoft/liberica-openjdk-*、cimg/openjdk等镜像/发行版；
对于滚动标签场景（如当前值为21-jre这类major(-suffix)形态），还会切换为docker版本规则，防止把滚动标签误升级成21.0.11_10-jre这种全精度标签；
对mise管理的java-version，则使用semver-partial版本规则，避免21被升级为21.0.11+9.0.LTS这样的全精度版本；
此外还覆盖了bellsoft/liberica-runtime-container与bellsoft/hardened-liberica-runtime-container两个容器镜像，其允许版本带jdk-/jre-前缀。

这套组合规则意味着：即使你用的不是 Docker 镜像而是 asdf/mise 之类的版本管理工具，LTS 限制同样生效。因此，若项目团队有明确的 Java 主版本策略，保留该 preset 即可；若需要紧跟最新 major 版本，再通过ignorePresets关闭。

Gradle 依赖更新

Gradle 是 JVM 生态中最主流的构建工具之一。Renovate 能够识别以下两种常见的依赖声明写法：

字符串形式：'group:artifact:version'，例如'org.springframework.boot:spring-boot-starter-web:3.2.0'；
Map 形式：(group: groupName, name: ArtifactName, version: Version)。

Gradle 文件支持范围

Renovate 可以更新以下类型的文件：

*.gradle/*.gradle.kts构建脚本；
在gradle.properties中声明版本号的依赖；
存放在*.lockfile文件中的 Gradle 锁文件；
任意目录下的*.versions.toml文件，或gradle目录内的*.toml文件（即 Gradle Version Catalogs 版本目录）；
gradle-consistent-versions插件生成的versions.props与versions.lock；
gradle/verification-metadata.xml中的签名与校验和（Gradle 依赖校验功能）。

这些支持范围与gradlemanager 的默认managerFilePatterns一一对应。查看 lib/modules/manager/gradle/index.ts 可以看到其正则配置：

managerFilePatterns: [ '/\\.gradle(\\.kts)?$/', '/(^|/)gradle\\.properties$/', '/(^|/)gradle/.+\\.toml$/', '/(^|/)buildSrc/.+\\.kt$/', '/\\.versions\\.toml$/', '/(^|/)versions.props$/', '/(^|/)versions.lock$/', ]

同时它声明了lockFileNames: ['gradle.lockfile']并支持锁文件维护。

明确不支持的场景

Renovate 对 Gradle 存在以下能力边界，需要特别注意：

需要额外配置才能运行的 Android 项目（例如需要配置 Android SDK）；
使用了版本范围（version ranges）的 Version Catalog；
Catalog 版本声明中使用reject、rejectAll约束；
单个 Catalog 声明中同时使用require、strictly、prefer中的多个约束；
自定义名称且不以.toml结尾的 Catalog；
位于gradle目录之外、名称不以.versions.toml结尾的 Catalog（除非通过managerFilePatterns配置覆盖）。

Gradle 插件支持

Renovate 同样支持 Gradle 插件的更新，兼容两种声明语法：

id(<pluginId>)语法；
kotlin(<kotlinPluginId>)快捷语法，它是id(org.jetbrains.kotlin.<kotlinPluginId>)的简写。

在编写packageRules时，理解 Gradle 插件的depName与packageName语义至关重要：

depName等于插件 ID（<pluginId>）；
packageName等于<pluginId>:<pluginId>.gradle.plugin。

这是 Gradle Plugin Marker Artifact（插件标记构件）命名约定的直接结果——每个插件在 Maven 仓库中都有一个对应的<pluginId>.gradle.plugin标记构件，Renovate 正是依据它来定位插件版本。因此，若要针对某个插件写匹配规则，应使用形如matchPackageNames: ['org.springframework.boot:org.springframework.boot.gradle.plugin']的写法。

Gradle Wrapper 更新

Renovate 可以更新项目的 Gradle Wrapper，涉及的文件包括：

版本来源声明：gradle/wrapper/gradle-wrapper.properties；
伴随文件：gradlew、gradlew.bat以及gradle/wrapper/gradle-wrapper.jar。

工作原理

更新流程如下：

Renovate 从gradle-wrapper.properties的distributionUrl中提取当前使用的 Gradle 版本；
确定版本后，通过gradle-version数据源查找更新的版本；
找到新版本后，调用 Gradle Wrapper 自身完成升级（即 Gradle 官方推荐的./gradlew wrapper --gradle-version X.Y.Z方式）。

提取逻辑在 lib/modules/manager/gradle-wrapper/extract.ts 中实现，它调用extractGradleVersion得到版本与 URL，然后构造datasource: GradleVersionDatasource.id、versioning: gradle的依赖对象。具体的正则位于 lib/modules/manager/gradle-wrapper/utils.ts：

/^(?:distributionUrl\s*=\s*)(?<url>\S*-(?<version>\d+\.\d+(?:\.\d+)?(?:-\w+)*)-(?<type>bin|all)\.zip)\s*$/m

从该正则可以确认一个重要约束：distributionUrl必须指向.zip文件，版本号必须包含在文件名中，且发行类型必须是官方发行类型bin或all之一。不满足这些条件的distributionUrl无法被解析，Renovate 会记录 debug 日志并跳过更新。

镜像与自定义发行版支持

由于 Renovate 以gradle-wrapper.properties中的distributionUrl作为更新基准，因此非官方来源同样受支持。这可以用于：

通过代理服务器托管官方发行版；
提供离线镜像；
提供自定义的 Gradle 发行版（例如在团队内统一分发的、内置公司级基础配置的发行版）。

但可用版本始终由gradle-version数据源决定。当你的自定义来源可用版本与官方不一致，或默认数据源（services.gradle.org的/versions/all接口）因网络限制无法访问时，可以通过packageRule重新配置该数据源：

{ "packageRules": [ { "matchDatasources": ["gradle-version"], "registryUrls": [ "https://domain.tld/repository/custom-gradle-wrapper/versions.json" ] } ] }

执行 Wrapper 的安全前提与锁文件更新

需要强调的是，Renovate并不会默认执行 Gradle Wrapper。从 lib/modules/manager/gradle/readme.md 可以看到：只有自托管管理员在allowedUnsafeExecutions中配置了gradleWrapper选项时，Renovate 才会执行./gradlew（Windows 上为gradlew.bat）。这是出于供应链安全考虑——执行仓库内的 Wrapper 脚本存在被恶意代码利用的风险，相关讨论见 security-and-permissions.md。

此外，该 manager 对锁文件的更新策略如下：

锁文件维护（lockFileMaintenance）时，在根项目与子项目上执行./gradlew :dependencies --write-locks；
常规依赖更新时，通过--update-locks命令行参数自动更新锁状态条目；
由于这些命令输出可能非常庞大，除stderr中的错误外，其余文本会被丢弃。

对于gradle/verification-metadata.xml的依赖校验，Renovate 在检测到<verify-metadata>true</verify-metadata>或<verify-signatures>true</verify-signatures>时，会用./gradlew --write-verification-metadata <hashTypes> dependencies更新内容，并沿用文件中已有的哈希类型。注意：Gradle 允许md5和sha1算法，但 Renovate 出于碰撞攻击风险会忽略这两种算法，遇到时统一改用sha256。

另外，执行 Wrapper 时的 Java 版本约束也是自动推导的。在 lib/modules/manager/gradle-wrapper/utils.ts 的getJavaConstraint中，Renovate 会结合当前 Gradle 主版本、gradle/gradle-daemon-jvm.properties中的toolchainVersion以及build.gradle(.kts)中声明的 Java toolchain 语言版本，推导出兼容的 Java 版本范围，从而为 Wrapper 运行选择合适的 JDK。

Maven 依赖更新

Renovate 可以更新 Mavenpom.xml中的依赖版本。mavenmanager 使用官方 Maven 版本规则解析版本号，且要求 XML 文件声明官方命名空间才能被正确解析（包括pom.xml与extensions.xml）。

Maven 文件支持

Renovate 会搜索仓库中所有pom.xml文件并独立处理（同时支持pom.template.xml模板文件）；
还会解析以下位置的settings.xml：
- .mvn/settings.xml
- .m2/settings.xml
- settings.xml

settings.xml中出现的任何仓库 URL 都会被作为registryUrls附加到提取出的依赖上，从而自动实现私有 Maven 仓库的版本查询。

对应的默认文件匹配模式位于 lib/modules/manager/maven/index.ts：

managerFilePatterns: [ '/(^|/|\\.)pom\\.xml$/', '/(^|/)pom\\.template\\.xml$/', '/^(((\\.mvn)|(\\.m2))/)?settings\\.xml$/', '/(^|/)\\.mvn/extensions\\.xml$/', ]

能力边界

从 lib/modules/manager/maven/readme.md 可以了解到两点限制：

mavenmanager 支持 Spring Boot OCI 打包中的镜像定制（Image Customizations），且registryAliases仅可用于容器镜像引用场景；
目前 Maven properties 不支持用于 buildpack 相关依赖。

自定义仓库与认证配置

Gradle manager 在版本查询时使用maven数据源，因此你可以通过统一的 hostRules 机制配置更多仓库并启用认证访问。

通过 config.js 配置 Artifactory 认证

下面的示例展示了如何在自托管config.js中配置 Renovate 访问 Artifactory，用户名与密码通过环境变量注入，避免明文写入配置文件：

module.exports = { hostRules: [ { hostType: 'maven', matchHost: 'https://artifactory.yourcompany.com/', username: process.env.ARTIFACTORY_USERNAME, password: process.env.ARTIFACTORY_PASSWORD, }, ], };

覆盖版本查询仓库

你也可以通过packageRules覆盖maven数据源使用的仓库列表：

module.exports = { packageRules: [ { matchDatasources: ['maven'], registryUrls: ['https://repo-a.tld/repo', 'https://repo-b.tld/repo'], }, ], };

结合上一节可知，settings.xml中解析出的仓库会自动注入registryUrls；而这里的显式配置优先级更高，适合多仓库聚合或覆盖默认源（例如 Maven Central）的场景。

Google Artifact Registry 接入

针对 Google Artifact Registry，Renovate 提供了多种认证方式，可按部署形态选择。

方式一：Application Default Credentials / Workload Identity（仅自托管）

在自托管环境中，可以正常配置 ADC（Application Default Credentials）或 Workload Identity，然后不要提供任何 username、password 或 token。Renovate 会通过google-auth-library自动获取凭据，无需额外配置 hostRules。

方式二：长期有效的服务账号凭据

当无法使用 ADC / Workload Identity 时，可以使用 JSON 服务账号结合Basic认证：

username 固定为_json_key_base64；
password 为完整的 Google Cloud Platform 服务账号 JSON。

为避免 JSON-in-JSON 包裹带来的转义问题，需要先将服务账号 JSON 做 Base64 编码。操作步骤如下：

下载服务账号 JSON 并保存在本地，确保该账号对制品只有read（且仅read）权限；
执行cat service-account.json | base64完成 Base64 编码；

将编码后的凭据写入配置：

若写入自托管配置文件：

{ "hostRules": [ { "matchHost": "europe-maven.pkg.dev", "username": "_json_key_base64", "password": "<base64 service account>" } ] }

若写入仓库内的 Renovate 配置文件，则需先对密码做encrypt加密后再添加：

{ "hostRules": [ { "matchHost": "europe-maven.pkg.dev", "username": "_json_key_base64", "encrypted": { "password": "<encrypted base64 service account>" } } ] }

最后在仓库 Renovate 配置文件的packageRules中，为maven与gradle两个 manager 指定 Artifact Registry 仓库地址：

{ "packageRules": [ { "matchManagers": ["maven", "gradle"], "registryUrls": [ "https://europe-maven.pkg.dev/<my-gcp-project>/<my-repository>" ] } ] }

这样，Maven 与 Gradle 项目的版本查询都会走 Artifact Registry，配合前一步的 hostRules 认证即可完成端到端的私有制品仓库接入。

小结

Renovate 对 Java 生态的支持覆盖了从构建脚本解析、插件更新、Wrapper 自升级到私有仓库认证的完整链路：gradle与maven两个 manager 承担依赖提取，gradle-wrappermanager 基于distributionUrl正则完成 Wrapper 版本管理，workarounds:javaLTSVersions提供开箱即用的 LTS 约束，而 hostRules 与 registryUrls 则解决了企业内网最常见的私有仓库认证与版本源覆盖问题。理解这些底层实现细节（如 lib/modules/manager/gradle-wrapper/utils.ts 中的提取正则、lib/config/presets/internal/workarounds.preset.ts 中的 LTS 白名单），能帮助你在实际项目中更精准地编写packageRules与hostRules，将 Java 依赖更新真正纳入自动化流水线。

【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考