GitHub Actions 中 setup-java 步骤详解：JDK 设置与 Maven 依赖缓存

1. 引言

在 GitHub Actions 工作流中，Java 项目的构建通常需要配置 JDK 环境并管理依赖缓存，以加速构建过程。actions/setup-java是一个官方 Action，它简化了这些任务。本文将详细解析该步骤如何设置 JDK 并启用 Maven 依赖缓存。

2. actions/setup-java 概述

actions/setup-java是 GitHub 官方提供的 Action，用于在 runner 环境中设置指定的 Java 开发工具包（JDK）版本。它的核心功能包括：

• JDK 安装与配置：自动下载、安装并配置指定版本（如 Java 8, 11, 17, 21）的 JDK。
• 环境变量设置：自动设置JAVA_HOME和将 JDK 的bin目录添加到PATH。
• 构建工具集成：支持 Maven、Gradle 等，并能与依赖缓存功能协同工作。

3. 基础用法：设置 JDK

以下是一个基础示例，展示如何在 workflow 中使用actions/setup-java来设置 JDK 17。

jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up JDK 17 uses: actions/setup-java@v4 with: java-version: '17' distribution: 'temurin' # 可选：指定发行版，如 'temurin', 'zulu', 'corretto'

参数说明：

• java-version：指定所需的 Java 版本，支持主版本号（如 '8', '11', '17'）或精确版本。
• distribution：指定 JDK 发行版，默认为 'temurin'（Adoptium Temurin）。其他选项包括 'zulu' (Azul Zulu), 'corretto' (Amazon Corretto) 等。

执行此步骤后，runner 中即可使用java -version和javac等命令。

4. 启用 Maven 依赖缓存

Maven 项目在每次构建时都会下载依赖，这可能会消耗大量时间。actions/setup-java可以与 GitHub Actions 的缓存功能集成，自动缓存 Maven 本地仓库（~/.m2/repository），从而显著提升后续构建的速度。

- name: Set up JDK 17 with Maven cache uses: actions/setup-java@v4 with: java-version: '17' distribution: 'temurin' cache: 'maven' # 关键参数：启用 Maven 依赖缓存

核心机制：

• 当cache: 'maven'被设置时，该步骤会自动计算项目pom.xml文件的哈希值（如果存在多个模块，则会考虑所有相关的pom.xml）。
• 此哈希值作为缓存的 key。如果缓存命中，则直接恢复~/.m2/repository目录；如果未命中或pom.xml发生变化，则在构建结束后将新的依赖缓存起来。
• 这确保了只有在依赖声明发生变化时才需要重新下载依赖。

5. 完整工作流示例

下面是一个集成了 JDK 设置、Maven 缓存和构建步骤的完整工作流示例。

name: Java CI with Maven Cache on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up JDK 17 with Maven cache uses: actions/setup-java@v4 with: java-version: '17' distribution: 'temurin' cache: 'maven' name: Build with Maven run: mvn -B clean compile --file pom.xml name: Run tests run: mvn -B test --file pom.xml

6. 高级配置与技巧

6.1 自定义缓存路径与 key

除了使用默认的 Maven 缓存，你还可以通过cache-dependency-path参数指定其他依赖文件（如 Gradle 的build.gradle或gradle.lockfile）来启用缓存。

- name: Set up JDK with custom cache uses: actions/setup-java@v4 with: java-version: '11' distribution: 'zulu' cache: 'gradle' cache-dependency-path: | **/build.gradle **/gradle.lockfile

6.2 多 JDK 版本矩阵测试

可以利用 GitHub Actions 的矩阵策略，在多个 JDK 版本上并行运行测试。

jobs: test: runs-on: ubuntu-latest strategy: matrix: java: [ '8', '11', '17', '21' ] steps: - uses: actions/checkout@v4 - name: Set up JDK ${{ matrix.java }} uses: actions/setup-java@v4 with: java-version: ${{ matrix.java }} cache: 'maven' - run: mvn -B test

6.3 服务器发布配置

如果你的项目需要发布到 Maven 中央仓库或 GitHub Packages，可以在 setup-java 步骤中配置发布所需的设置。

- name: Set up JDK for publishing uses: actions/setup-java@v4 with: java-version: '17' distribution: 'temurin' cache: 'maven' server-id: github # 用于发布到 GitHub Packages server-username: MAVEN_USERNAME server-password: MAVEN_PASSWORD gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }} gpg-passphrase: MAVEN_GPG_PASSPHRASE

7. 总结

actions/setup-java步骤是 GitHub Actions 中构建 Java 项目的基石。通过java-version和distribution参数，它可以灵活地设置所需的 JDK 环境。而cache: 'maven'参数则能智能地缓存依赖，大幅减少构建时间。结合矩阵测试、自定义缓存路径等高级功能，可以构建出高效、可靠的 Java CI/CD 流水线。

建议在实际项目中始终启用依赖缓存，并定期检查actions/setup-java的版本更新，以获取性能改进和新特性支持。