actions/setup-java v6 实测指南：从安装 JDK 到 Maven 发布配置

它解决什么问题，谁需要它

GitHub Actions 的 runner 默认没有预装 Java，即使有，版本也未必匹配项目要求。actions/setup-java 是官方 Action，负责下载指定发行版和版本的 JDK，设置 JAVA_HOME 和 PATH，让后续步骤可以直接运行 java、mvn 或 gradle。它面向所有在 GitHub Actions 上构建 JVM 生态项目的工程师，包括 Java、Scala、Kotlin、Gradle、Maven 和 sbt。除了基础安装，它还处理三个常见痛点：依赖缓存、Maven 发布配置、多 JDK 共存。如果你只是想在 CI 里跑一个 java -version，它当然够用；但如果你需要发布到 Maven Central 或管理多个 JDK 版本，它提供的功能远超一个安装器。

安装机制：从下载到缓存，v6 新增了什么

核心逻辑是输入 distribution 和 java-version，Action 从对应发行版的远程元数据解析具体版本，下载归档，解压后写入 PATH 与 JAVA_HOME。v6 引入 java-version: latest，会解析发行版最新的稳定 GA 版本，而不是硬编码一个版本号。另一个新增是 force-download: true，可以绕过工具缓存，强制重新下载，适合需要可复现构建的场景。v6 还默认验证下载归档的校验和，只要发行版发布了权威校验和；对于 Temurin 和 Microsoft 构建，包签名验证默认开启。这意味着供应链攻击的门槛提高了，但代价是每次安装多一步校验，对慢网络环境可能增加几秒。JDK 下载本身也会被缓存，由 cache 输入触发，可用 cache-jdk 单独控制。

缓存策略：Maven、Gradle、sbt 以及 JDK 本身

依赖缓存是 setup-java 的一个重要卖点。设置 cache: maven、gradle 或 sbt，Action 会为对应构建工具缓存依赖目录，并生成缓存 key。v6 改进了 key 的敏感性：Maven 的 key 现在包含 .mvn/extensions.xml，Gradle 的包含 gradle.properties。这意味着如果 Maven 扩展或 Gradle 依赖属性变化，缓存不会错误命中。v6 还新增 cache-path 支持自定义缓存路径，以及 cache-read-only: true 用于只恢复不更新。JDK 本身也自动缓存，但注意这与依赖缓存是分开的，cache-jdk 可以独立开关。对于频繁运行的 CI，JDK 缓存能显著减少网络请求，但有一个细节：v6 的“warm JDK-cached jobs”可以重用缓存的发行版元数据，避免调用供应商 API，同时在供应商故障时回退到旧元数据。这降低了外部 API 成为单点故障的风险，但如果你需要绝对最新的版本，可能偶尔会拿到稍旧的元数据。

多 JDK 与 Maven Toolchains：何时需要 set-default: false

一个 job 中多次调用 setup-java 可以安装多个 JDK。默认每次调用会覆盖 JAVA_HOME 和 PATH，但 v5 引入 set-default: false 后，可以安装一个 JDK 而不改变环境变量。这适合需要多个 JDK 共存的项目，例如用 Java 17 编译、用 Java 21 运行测试。对于 Maven 用户，Action 能生成 toolchains.xml，让 Maven Toolchains 插件按版本选择 JDK。v6 增加了对 toolchain ID 数量不匹配的报错，避免配置错误被静默忽略。但注意，文档提到“preserving toolchain entries across repeated action invocations”，意味着多次调用时 toolchain 条目会被保留，这可能是期望行为，也可能导致意外累积，需要你根据工作流自行验证。

Maven 发布配置：签名、凭据与 GPG 的变化

发布到 Maven Central 需要配置 settings.xml 中的服务器凭据和 GPG 签名。setup-java 可以生成这些配置，v6 做了几个关键调整。输入名从 server-username 改为 server-username-env-var，避免被误认为是秘密值，旧名称仍可用但会报警告。GPG 密码现在通过 gpg.passphraseEnvName 传递，而不是旧的 gpg.passphrase 服务器条目。这是一个破坏性变更：要求 maven-gpg-plugin 3.2.0 或更高版本，否则签名会失败。v6 还支持多个服务器凭据和自定义依赖解析仓库，这对需要从私有仓库拉取依赖的团队有用。另一个安全改进是签名密钥导入到隔离的临时 GPG home，而不是 runner 的默认 keyring，减少了密钥泄漏面。如果你已经在用旧版本，升级 v6 时必须检查 Maven 插件版本，否则发布流程会静默中断。

版本文件与发行版支持：.sdkmanrc 的便利与陷阱

除了直接指定 java-version，setup-java 支持从 .java-version、.tool-versions 和 .sdkmanrc 读取版本。v5 起，.sdkmanrc 还能提供发行版信息，自动检测 SDKMAN 和 asdf 的供应商标识。这意味着你可以在仓库根目录维护一个 .sdkmanrc，Action 自动匹配发行版，减少 workflow 中的重复配置。但注意，.tool-versions 通常被 asdf 使用，格式是“工具名 版本”，setup-java 需要从中解析 java 条目，如果文件里有多行，它是否能正确提取？文档没有明确说明，建议自行测试。发行版支持范围很广，包括 Temurin、Microsoft、Oracle OpenJDK、Red Hat、Liberica、GraalVM、Zulu、Corvette、Dragonwell、Tencent Kona 等。v6 移除了 AdoptOpenJDK 旧发行版，必须改用 temurin 或 semeru。对于 Alpine 用户，v6 扩展了对 Dragonwell、Corretto、Zulu 和 Liberica 的 musl 原生构件支持，这解决了在 Alpine 上跑 Java 的经典难题。

维护成本与许可证：升级 v6 前要确认什么

setup-java 是 MIT 许可证，可以自由使用和修改。但它的维护节奏很快，v6 发布于 2026 年 8 月，v5 和 v4 仍收到补丁，但 v1 到 v4 已明确弃用。升级成本有几个方面：v5 要求自托管 runner 版本 v2.327.1 以上，因为运行时升级到 Node 24；v6 迁移到 ESM，可能影响自定义包装脚本。如果你使用了被重命名的输入，如 server-username，需要更新工作流，虽然旧名称仍可用但会报警告。另一个潜在成本是缓存 key 的变化，v6 包含更多文件，可能导致缓存命中率下降，首次运行会重新下载依赖。对于 GPG 配置，必须升级 maven-gpg-plugin，这是一个硬性要求。整体而言，维护成本可控，但不要长期停留在 v4，因为安全修复会集中在 v6。

编辑结论

对于使用 GitHub Actions 构建 Java、Scala、Kotlin、Gradle、Maven 或 sbt 项目的团队，actions/setup-java v6 是官方维护且功能完整的首选。它解决了 JDK 版本管理、依赖缓存和发布配置三个高频痛点，尤其是 v6 的自动校验和与签名验证，降低了供应链风险。不建议在以下情况使用：需要支持已被移除的 AdoptOpenJDK 旧发行版，或自托管 runner 版本低于 v2.327.1（v5 起要求 Node 24）。采用前应验证：确认你的 Maven GPG 插件版本不低于 3.2.0，因为 v6 改用 gpg.passphraseEnvName 传递密码；检查 .sdkmanrc 或 .tool-versions 中的发行版标识是否被自动识别；若使用缓存，需确认 cache-jdk 与 cache-path 的组合符合你的清理策略。最后，v1 至 v4 已弃用，务必直接引用 @v6。

官方来源

1. Official README
2. Project repository
3. Release notes