OpenSSL 4 預設值切換不代表所有 macOS CI 都會失敗；先用同一個專案和 Runner 做版本對照測試，只有確認依賴仍需要 OpenSSL 3 時，才明確固定版本，不要依賴 Runner 的未指定預設值。本文依據截至 2026 年 10 月 23 日已公告的狀態整理驗收方式；公告所列的切換仍是計畫，並非已全面生效。
適合維護 GitHub Actions macOS 工作流程、需要核對原生依賴或 Ruby、Python 整合的開發者。
也適合管理建置節點、需要決定適配新版本、固定 OpenSSL 3 或暫緩切換的 DevOps 工程師。
計畫狀態提醒：Runner Images 公告列出的推出窗口為 2026 年 11 月 2 日至 11 月 8 日，實際安排以公告後續更新為準；公告同時說明 OpenSSL 3 會保留。這是預設命令版本調整，不等於 OpenSSL 3 已移除，也不表示所有專案都會出現不相容問題。查看 Runner Images 官方公告
先確認預設值調整的適用範圍
這次檢查的核心不是「OpenSSL 4 能不能用」，而是工作流程是否把某一個主版本、命令列行為或函式庫載入方式寫死。官方公告指向 macOS 26 與 Xcode 27 Runner 的 openssl 預設命令版本，並未宣告所有 macOS Runner、所有應用程式或所有 OpenSSL 3 使用情境都會同步失效。公告中的適用範圍與推出計畫
截至上述核對日期，公告中的推出窗口尚未開始，因此不應把計畫描述成已全面完成。發布前與切換期間，還要對照目標映像的軟體清單；清單反映的是特定映像內容，應與工作流程實際選用的 Runner 標籤一起閱讀。macOS 26 Runner 軟體清單
OpenSSL 官方將 4.0 列為主版本變更，並指出使用已棄用 API 的程式可能需要調整；這提示的是要檢查相依程式與 API 使用狀況，而不是斷言專案必然不相容。OpenSSL 4.0 遷移指南
先從命令路徑與版本判斷腳本風險
容易被忽略的第一種故障，是腳本把「目前的 openssl 指令」當成固定不變的工具。例如，腳本可能直接呼叫 PATH 中第一個找到的 openssl，只接受特定主版本字串，或解析格式與版本綁定的輸出。預設值變更後，命令仍然存在，但檢查邏輯可能將版本差異誤判為建置失敗。
在 GitHub Actions 的工作流程中加入診斷輸出，並將結果保留在同一個 Job 日誌：
command -v openssl
type -a openssl
openssl version -a
openssl version 用來顯示工具版本，詳細輸出選項可參考 OpenSSL version 命令文件。command -v 與 type -a 則用來確認目前 Shell 如何解析命令，以及是否有多個候選路徑。若版本輸出符合預期，但任務仍失敗，就要再確認腳本是否呼叫其他絕對路徑、使用不同 Shell，或在安裝步驟後改寫了 PATH。
逐項檢查下列情況，避免以「版本不同」代替根因分析：
- [ ] 腳本是否用字串比對限制 OpenSSL 主版本？
- [ ] 是否以固定欄位、固定格式解析
openssl version的輸出？ - [ ] 指令是否使用 PATH 中的
openssl，還是硬編碼路徑？ - [ ] 安裝依賴、啟用快取或修改環境變數後，命令解析結果是否改變？
- [ ] GitHub Actions 日誌是否保留了 Runner 標籤、命令路徑和版本輸出？
若工作流程需要跨 Runner 比較，應讓每個 Job 顯示相同的診斷資訊；GitHub Actions 也有工作流程命令可將資訊寫入日誌或設定輸出，但輸出格式與後續步驟應按其文件處理。GitHub Actions 工作流程命令文件
再把原生依賴拆成編譯、連結與載入
原生依賴出錯時，先從日誌定位故障階段，不要把所有訊息都歸類為「OpenSSL 不相容」。缺少標頭檔或 API 宣告，通常要查編譯環境與依賴版本；符號解析失敗要查連結設定；程式啟動後才找不到動態函式庫，則應核對執行期載入路徑。三者的修復位置不同，單純改 PATH 未必能處理後兩者。
檢查建置輸出時，分別記錄編譯器實際使用的標頭檔、連結器選到的函式庫，以及執行時載入的動態函式庫。Apple 的文件說明了依賴執行路徑與動態函式庫定位的關係，可用來協助判斷「建置成功、執行失敗」這類問題。Apple 動態函式庫執行路徑文件
對 Ruby、Python 或其他包含原生擴充的執行環境，也要確認擴充模組建置時與執行時所使用的函式庫。依賴文件若聲明需要特定 OpenSSL 主版本，應先核對該依賴的官方相容說明，再以專案的實際建置和測試結果作結論；不能只因 Runner 上有 OpenSSL 4，就推定所有依賴都已連結到它。
接著驗收 TLS 與憑證任務的實際行為
憑證與 TLS 工作常被腳本包裝成多個步驟：產生金鑰、建立憑證、檢查欄位，再交給應用程式或測試服務使用。即使單獨執行某一條 OpenSSL 命令成功，也只能證明該命令在當下環境有結果，不能證明完整流程的參數、輸出與應用程式載入的函式庫都符合預期。
驗收時應逐項記錄：實際命令及參數、退出狀態、產生的檔案、下游工具是否能讀取，以及 TLS 測試是否完成。若工作流程使用 x509 子命令，應按任務所需的操作核對其官方文件，不要只用「憑證檢查通過」作為全鏈路相容證據。OpenSSL x509 命令文件
最後比對本機與 Runner 的執行環境
本機成功、Runner 失敗時，不宜立即認定是 OpenSSL 版本造成。兩邊的作業系統映像、CPU 架構、PATH、依賴來源、快取內容與執行期載入路徑都可能不同。即使本機與 CI 回報相同的版本號，實際使用的函式庫也未必相同。
先在同一提交上留存 CI 的命令路徑、版本輸出與依賴建置日誌，再用同樣的檢查方式記錄本機結果。確認 Runner 標籤與映像內容後，才將差異縮小到工具版本或相依項目。GitHub Actions 的 Runner 選擇文件可用來核對 Job 實際指定的執行環境。GitHub Actions Runner 選擇文件
另一個常見干擾因素是快取：若依賴二進位檔或建置產物來自舊環境，當次測試可能沒有真正重建相關元件。比對時應保存是否命中快取、是否執行原生依賴重建，以及失敗發生在建置還是執行階段，避免將工具鏈漂移誤判成版本回歸。
用對照驗收結果選擇切換或固定版本
決策應基於實際專案測試，而非單看 Runner 的預設版本。先在受控工作流程中跑完命令檢查、原生依賴建置、應用程式啟動、憑證與 TLS 任務，再決定是否擴大切換。若依賴尚未支援 OpenSSL 4，或測試結果不穩定，可依官方公告所述方式明確選擇 OpenSSL 3；如果各項任務均通過，則可更新腳本與依賴，避免長期依賴未指定的預設值。
| 選項 | 適用條件 | 必須驗收 | 主要風險與回退依據 |
|---|---|---|---|
| 適配 OpenSSL 4 | 腳本和依賴已確認支援新主版本，代表性流水線結果一致 | 命令輸出、原生依賴重建、應用程式載入、憑證與 TLS 任務 | 若 API、連結或執行期載入失敗，暫停擴大切換並修正相依項目 |
| 明確固定 OpenSSL 3 | 依賴官方說明仍要求 OpenSSL 3，或對照測試未通過 | 固定方式是否生效、PATH 與載入路徑是否一致、完整測試是否通過 | 若僅固定 CLI、應用程式卻載入其他函式庫，仍不能視為驗收完成 |
| 暫緩切換 | 尚無可比較日誌、關鍵任務未納入測試，或推出狀態仍待確認 | 建立基線、確認 Runner 映像與公告更新、補齊失敗任務 | 不以一次成功或舊快取結果作為放行依據 |
| 故障證據 | 優先核對的層次 | 下一步 |
|---|---|---|
| 版本檢查腳本中止，但命令存在 | PATH、版本字串與輸出解析 | 對照實際路徑，修正硬編碼假設或明確選擇版本 |
| 編譯時找不到標頭檔或 API | 開發標頭與依賴版本 | 查明建置工具實際選用的標頭及相容說明 |
| 連結時出現未解析符號 | 連結器輸入與 API 使用 | 核對連結到的函式庫版本及程式使用的 API |
| 程式啟動後找不到函式庫 | 執行期載入路徑 | 檢查實際載入項目與執行路徑設定 |
| 憑證命令成功、下游 TLS 測試失敗 | 命令參數、輸出及應用程式載入庫 | 重跑完整流程，分別留存 CLI 與應用程式結果 |
| 驗收階段 | 必留證據 | 放行條件 |
|---|---|---|
| Runner 與命令 | Runner 標籤、映像清單、命令路徑與版本輸出 | 已確認執行環境及 OpenSSL 命令來源 |
| 原生依賴 | 編譯、連結日誌及依賴相容依據 | 建置完成，且連結目標符合預期 |
| 執行期 | 動態函式庫載入資訊與應用程式測試結果 | 程式能在目標 Runner 正常啟動 |
| 憑證與 TLS | 命令、產物、退出狀態及下游測試日誌 | 代表性憑證與 TLS 流程均通過 |
| 回退準備 | 版本選擇、失敗條件與回退步驟 | 失敗時可回到明確指定且已驗收的版本 |
常見問題
預設版本切換後，所有 macOS CI 都會自動失敗嗎？
不會。公告描述的是特定 Runner 上預設命令版本的調整，OpenSSL 3 亦會保留。只有腳本、依賴或 TLS 流程對版本、選項或輸出有特定假設時，才需要修正或選擇固定版本。應以專案流水線測試決定，而不是把計畫公告當成故障通知。
GitHub Actions macOS Runner 上怎樣查明 openssl 使用哪個版本？
在 Job 日誌輸出 command -v openssl、type -a openssl 與 openssl version -a，再一併保存 Runner 標籤。這能指出命令解析路徑及工具回報版本，但不能單獨證明應用程式載入了同一個函式庫；原生依賴還要另外檢查連結與執行期載入結果。
需要繼續用 OpenSSL 3 時，應該怎樣設定 macOS Runner？
先查看公告與目標映像軟體清單，按官方公告提供的方式明確選擇版本，並在日誌中驗證命令路徑和版本輸出。接著重建原生依賴、檢查執行期載入函式庫並重跑 TLS 任務。不要假設固定命令列工具就會自動固定所有應用程式的連結結果。
OpenSSL 4 切換前，哪些 CI 任務不能漏測？
除了版本與腳本判斷，還要驗收原生依賴的編譯、連結、程式啟動與函式庫載入，並測試實際使用的憑證和 TLS 流程。若 Ruby、Python 或其他執行環境包含原生擴充，也要在 CI 中重新建置並執行相關測試，避免只驗證獨立命令。
如果本機或既有 CI 難以重現相同的 macOS Runner，應先盤點現有方案的限制：本機節點可能與 CI 映像、依賴來源及載入路徑不同；共用建置節點較難隔離版本對照；未固定的雲端預設值則可能隨映像更新而改變。對需要真實 macOS 環境完成對照驗收的團隊，獨立遠端 Mac 節點可作為補充測試環境；若只是偶爾查詢版本、而現有 Runner 已能穩定重現，就沒有必要額外租用。可先了解 RUVCLOUD 遠端 Mac 環境，再按測試週期評估 RUVCLOUD 方案與計費資訊。最後仍應以 Runner Images 公告及目標映像軟體清單核對推出狀態，避免把計畫日期當成已生效日期。