actions/setup-java：在 GitHub Actions 固定 JDK、快取與簽章檢查
使用特定版本的 Java 設定 GitHub Actions 工作流程。
秒懂
- 它是什麼？
- GitHub Actions 官方動作，支援多個 Java 發行版、版本檔案、依賴快取、JDK 快取與可選簽章驗證。
- 適合誰用？
- setup-java 會輸出 `distribution`、`version`、`path`、`cache-hit` 和 `cache-primary-key`，這些值適合提供給後續步驟或診斷。它也能用 `set-default: false` 安裝 JDK 而不改變 JAVA_HOME 或 PATH，適合同一 job 需要多個 JDK 的情況。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 5 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
v6 的版本判斷要寫進 workflow
素材中的 README 已把 v6 列為最新穩定 release，並明確說明 v1 到 v4 已棄用；基線的舊判斷把 v5 視為穩定、v6 視為開發中，已與最新素材不一致。v6 的執行時升級到 Node 24，使用自託管 runner 時要確認 runner 至少是 v2.327.1。
版本不能只看 action 名稱。企業 workflow 應把 `actions/checkout@v7`、`actions/setup-java@v6` 與 runner 版本一起列入變更審查，並移除仍引用 `@v1` 至 `@v5` 的舊工作流。若暫時測試 main 分支，必須把它視為實驗設定，不要與 release tag 混用。
GitHub Actions 中的 Java 版本不能只由開發者本機決定。把 `.java-version` 或 `.tool-versions` 放進 repository 後，應檢查所有 matrix job 是否都讀同一檔案，並確認 `java-version-file` 沒有和 `latest` 同時使用。對需要兩個 JDK 的工作，可先用 `set-default: false` 安裝次要版本，再用輸出 `path` 明確呼叫它，避免 PATH 被後續步驟悄悄改寫。
在actions/setup-java的「v6 的版本判斷要寫進 workflow」這個範圍，記錄輸入、輸出與時間點比只記錄成功更有用。測試紀錄至少應包含第 1 個章節提到的命令、檔案或端點，以及實際看到的錯誤文字。若結果與 README 不同，先保留原始輸出，再判斷是版本、權限、網路或資料本身造成。
這項檢查也能形成升級前後的比較基準：固定同一個 actions/setup-java 設定，重新執行相同案例，檢查功能結果、日誌可讀性和失敗後的復原動作。沒有明確輸出的地方，就標記為文件未說明，不把推測寫成專案承諾。
對 actions/setup-java@v6 的最小回歸還要確認 Node 24 action runtime 能在目前 runner 啟動，並把 `java --version` 的實際輸出與 setup-java 的 path output 一起保存。這能區分 JDK 下載問題和 runner 相容性問題。
distribution 與 java-version 是核心輸入
README 的基本範例使用 `distribution: temurin`、`java-version: 25`，也示範 `distribution: microsoft`。版本可寫主版本、具體版本、語意版本範圍、早期存取版本或 `latest`。`latest` 不能與 `java-version-file`、早期存取版本或 `distribution: jdkfile` 一起使用。
另一路是從 `.java-version`、`.tool-versions` 或 `.sdkmanrc` 讀取版本；`.sdkmanrc` 還可用 `java=21.0.5-tem` 這類後綴自動識別發行版。這讓版本來源可交給倉庫管理，但也表示修改版本檔會影響所有 workflow，應讓 pull request 明確呈現該檔案變更。
快取與安全設定也要放進 workflow review。pull request 使用 `cache-read-only: true` 時，觀察 cache miss 是否仍可完成建置；`force-download: true` 配合 `verify-signature: true` 時，則確認 Temurin 或 Microsoft 的下載確實經過驗證。自託管 runner 若低於 v2.327.1，Node 24 runtime 可能直接成為失敗原因，這應在 runner 管理端先核對，而不是修改 Java 程式碼。
在actions/setup-java的「distribution 與 java-version 是核心輸入」這個範圍，記錄輸入、輸出與時間點比只記錄成功更有用。測試紀錄至少應包含第 2 個章節提到的命令、檔案或端點，以及實際看到的錯誤文字。若結果與 README 不同，先保留原始輸出，再判斷是版本、權限、網路或資料本身造成。
十六種發行版不是同一個下載體驗
README 列出 Amazon Corretto、Alibaba Dragonwell、Oracle GraalVM、GraalVM Community、JetBrains Runtime、Tencent Kona、Liberica、Microsoft Build of OpenJDK、Oracle JDK、Oracle OpenJDK、SAP SapMachine、IBM Semeru、Eclipse Temurin、Azul Zulu 及自訂 `jdkfile`。不同供應商的版本、架構與套件變體可能不同。
因此 `java-version: 25` 只表達版本意圖，不能保證每個 distribution 都提供同樣的套件。矩陣測試應把 distribution、architecture、java-package 和 runner OS 分開記錄，並在步驟中執行 `java --version`，同時檢查 setup-java 的 `distribution`、`version` 和 `path` 輸出。
在actions/setup-java的「十六種發行版不是同一個下載體驗」這個範圍，記錄輸入、輸出與時間點比只記錄成功更有用。測試紀錄至少應包含第 3 個章節提到的命令、檔案或端點，以及實際看到的錯誤文字。若結果與 README 不同，先保留原始輸出，再判斷是版本、權限、網路或資料本身造成。
快取是依賴管理的一部分
動作支援 Maven、Gradle 與 sbt 依賴快取，也有 Maven 和 Gradle wrapper 快取，以及可獨立控制的 JDK 快取。`cache` 可設為 `maven`、`gradle` 或 `sbt`，鍵值會依作業系統、架構、套件管理器和依賴檔雜湊組成，`cache-read-only` 可用在 pull request 或矩陣作業。
快取命中不是建置正確的證明。測試時先清除快取跑一次，再重跑比較 `cache-hit`、下載時間與測試結果；修改 `pom.xml`、Gradle lockfile 或 sbt 依賴後，要確認雜湊真的產生新鍵。若依賴仍未更新，才去檢查 `cache-dependency-path` 與 `SEGMENT_DOWNLOAD_TIMEOUT_MINS`。
在actions/setup-java的「快取是依賴管理的一部分」這個範圍，記錄輸入、輸出與時間點比只記錄成功更有用。測試紀錄至少應包含第 4 個章節提到的命令、檔案或端點，以及實際看到的錯誤文字。若結果與 README 不同，先保留原始輸出，再判斷是版本、權限、網路或資料本身造成。
簽章驗證有明確限制
當發行版提供權威校驗和時，動作會自動驗證下載存檔；`verify-signature: true` 目前支援 Temurin 與 Microsoft。從 runner 工具快取解析的 JDK 不會重新下載或重新驗證，即使開啟此選項也是如此，必要時可用 `force-download: true`。
在安全敏感的 workflow 中，應區分「下載並驗證」與「直接使用 runner 預裝版本」。對不支援簽章的 distribution 開啟 `verify-signature` 會使 workflow 失敗，這是可預期的門檻。把 `force-download` 當成成本較高的強制路徑，並保留 action log 供稽核。
在actions/setup-java的「簽章驗證有明確限制」這個範圍，記錄輸入、輸出與時間點比只記錄成功更有用。測試紀錄至少應包含第 5 個章節提到的命令、檔案或端點，以及實際看到的錯誤文字。若結果與 README 不同，先保留原始輸出，再判斷是版本、權限、網路或資料本身造成。
輸出與升級驗收
setup-java 會輸出 `distribution`、`version`、`path`、`cache-hit` 和 `cache-primary-key`，這些值適合提供給後續步驟或診斷。它也能用 `set-default: false` 安裝 JDK 而不改變 JAVA_HOME 或 PATH，適合同一 job 需要多個 JDK 的情況。
適合採用者是以 GitHub Actions 建置 Java、Scala、Kotlin、Maven、Gradle 或 sbt 的團隊；第一個核驗應建立最小 workflow：checkout、`actions/setup-java@v6`、`java --version`，再加入實際建置與快取。升級時重跑版本檔、`set-default`、簽章與 cache hit 四組案例，不能只看 workflow 綠燈。
在actions/setup-java的「輸出與升級驗收」這個範圍，記錄輸入、輸出與時間點比只記錄成功更有用。測試紀錄至少應包含第 6 個章節提到的命令、檔案或端點，以及實際看到的錯誤文字。若結果與 README 不同，先保留原始輸出，再判斷是版本、權限、網路或資料本身造成。
編輯結論
setup-java 會輸出 `distribution`、`version`、`path`、`cache-hit` 和 `cache-primary-key`，這些值適合提供給後續步驟或診斷。它也能用 `set-default: false` 安裝 JDK 而不改變 JAVA_HOME 或 PATH，適合同一 job 需要多個 JDK 的情況。
適合採用者是以 GitHub Actions 建置 Java、Scala、Kotlin、Maven、Gradle 或 sbt 的團隊；第一個核驗應建立最小 workflow：checkout、`actions/setup-java@v6`、`java --version`，再加入實際建置與快取。升級時重跑版本檔、`set-default`、簽章與 cache hit 四組案例，不能只看 workflow 綠燈。
在actions/setup-java的「輸出與升級驗收」這個範圍，記錄輸入、輸出與時間點比只記錄成功更有用。測試紀錄至少應包含第 6 個章節提到的命令、檔案或端點，以及實際看到的錯誤文字。若結果與 README 不同，先保留原始輸出，再判斷是版本、權限、網路或資料本身造成。
社群筆記