macOS 27 Docker CI 怎麼部署自託管 Mac?2026 指南

截至 2026 年 10 月 4 日,GitHub 官方文件明確指出,需要執行 Docker container actions 或 service containers 的自託管 runner 必須使用 Linux。GitHub 的 runner 作業系統要求意味著:macOS 27 自託管 Mac 可以承接經過驗證的主機端 Docker 映像建置,但不能取代 Linux runner 執行這些容器工作。部署前先查 Docker Desktop 對 macOS 27 的支援狀態、團隊授權和目標環境權限;依賴容器 action 或 service container 的工作則分流到 Linux。
適合正在把 Docker 映像建置接入 GitHub Actions 的 DevOps 工程師,按部署流程搭建並驗證 Mac runner。
需要把 macOS 建置步驟與 Docker 工作流程串在一起的研發團隊,可用本文判斷工作該留在 Mac 還是交給 Linux。
評估雲端或租用 Mac 的負責人,則應先核對授權、虛擬化支援與後續維護責任。
最後更新於 2026 年 10 月 4 日;相容性與限制核對自 GitHub Actions、Docker 官方文件。macOS 27 的 Docker Desktop 支援狀態及租用環境能力,仍須依當期文件與目標主機實測確認。
macOS 27 Docker CI 自託管 Mac:先劃清工作邊界
不要先註冊 runner,再期待整條 Docker 流水線自然相容。先把工作流程拆成四類:主機端 shell 步驟、Docker 映像建置、Docker container actions,以及 service containers。只有前兩類可能適合在 Mac 主機上執行;後兩類有 GitHub 官方文件列出的 Linux 要求。
| 工作內容 | Mac runner 的判斷 | 派送前要確認 |
|---|---|---|
| 主機端 shell 步驟 | 可評估在 macOS 執行 | 腳本、工具與權限能否在目標主機使用 |
| 透過 Docker CLI 執行映像建置 | 可在目標環境實跑驗證 | Docker CLI 能連到 daemon,產物輸出符合工作流程需求 |
| Docker container actions | 不應視為 Mac runner 可承接 | 需要 Linux runner |
| service containers | 不應視為 Mac runner 可承接 | 需要 Linux runner |
Docker CLI 可用,不代表所有 Docker 相關工作都能在 Mac runner 執行。若同一個 job 混有 macOS shell 步驟與容器 action,先拆分工作,再設定 runner 路由;否則可能在工作開始後才遇到執行環境不符。
決策條件:
- 若工作只需要在 macOS 主機執行 shell 步驟,並由 Docker CLI 建置映像,先驗證 Docker Desktop,再讓 job 指向 Mac runner。
- 若工作需要 Docker container action 或 service container,將該 job 派送到 Linux runner。
- 若一個 job 同時需要兩種環境,先拆成互相依賴的工作,再以產物或工作流程依賴銜接;不要只因為 Mac 上有 Docker CLI 就把整個 job 留在 Mac。
- 若目標 Mac 無法安裝或啟動受支援的 Docker Desktop,回退到 Linux runner,或重新評估建置是否一定要在 Mac 主機上完成。
部署前:核對 Docker Desktop 支援、授權與主機權限
Docker Desktop 的 Mac 安裝文件要求使用其當期支援的 macOS 版本,並列出處理器架構與安裝條件。Docker Desktop Mac 安裝與系統需求應作為部署前核對依據。macOS 27 是否已列入支援範圍,不能由系統版本名稱推定;上線前要查看文件當下列出的版本,再在實際 runner 環境安裝和首次啟動。
也要確認安裝方式符合環境限制。Docker 文件說明 Mac 上的權限需求與首次執行可能涉及的系統操作;雲端或租用主機不一定允許所需的虛擬化功能、權限調整或圖形介面確認。Docker Desktop Mac 權限需求列出的條件,應逐項對照目標環境,而不是預設雲端 Mac 與個人 Mac 權限相同。
授權也要由團隊依實際使用情況確認。Docker 的 Desktop 授權條款說明不同組織和用途適用的條件;不能假設個人可用,就代表公司 CI 一定符合免費使用範圍。Docker Desktop 授權說明可用來核對目前條款。將團隊規模、用途與採購要求交由負責人確認,並保留判斷紀錄。
| 核對項目 | 部署前的通過條件 | 未通過時的處理 |
|---|---|---|
| macOS 與處理器架構 | 符合 Docker Desktop 當期安裝文件 | 暫緩安裝,先確認相容性 |
| 虛擬化與安裝權限 | 目標主機可完成安裝和首次啟動 | 改用可支援的環境,或回退至 Linux 建置 |
| 商業授權 | 團隊已依目前條款完成判定 | 先釐清授權,不要直接投入正式 CI |
| 主機端工作流程 | 已列出工具、憑據和產物需求 | 用測試 job 補齊環境條件 |
若部署人員需要確認帳戶或環境處理方式,可先查閱ProxyMac 使用說明。這不能取代 Docker 授權核對,也不能代替對目標主機執行安裝測試。
Runner 註冊與標籤:讓工作只落到預期主機
GitHub Actions self-hosted runner 可依需求註冊到 repository 或 organization。選擇範圍時,應同時考量誰負責維護、哪些工作流程可以使用,以及權限由誰管理。按 GitHub 提供的 runner 新增流程操作;可見的設定選項和管理權限依所在範圍而異,不要把某一個專案的操作畫面當成所有團隊都相同。GitHub 新增自託管 runner 的官方步驟可供逐步核對。
標籤要反映實際系統、架構和用途。GitHub 文件說明,工作流程可用標籤選擇符合條件的 runner;runner group 則可用於管理可供工作流程使用的 runner 範圍。GitHub runner 路由與標籤說明不要只用含義模糊的 mac 或 docker 標籤,也不要加上主機並未具備的能力標籤。
以下設定中的標籤只作為示例,必須與實際 runner 上已設定的標籤一致:
jobs:
docker-build:
runs-on: [self-hosted, macOS, ARM64, macos-27-docker]
steps:
- uses: actions/checkout@v4
- name: 建置映像
run: docker buildx build --tag example/app:ci --load .
若標籤拼法與 runner 設定不符,工作可能找不到可用主機;若標籤過寬,則可能派到不符合需求的 runner。自訂標籤應對應一項可驗證的條件,並在工作流程中明確選擇。
Docker Desktop Mac 安裝:先在目標環境完成啟動驗證
本機能安裝,不代表 CI 主機也能啟動。尤其租用或雲端環境,必須在實際交付的主機上檢查安裝條件、首次啟動流程與權限限制。不要預設虛擬化、特權設定或圖形介面確認已經開通;也不要在未驗證前承諾工作流程可用。
執行時保留一份簡單的環境紀錄:macOS 版本、處理器架構、Docker Desktop 版本、安裝結果與首次啟動結果。這些是排查相容性和回歸問題所需的事實,不是對速度或跨架構效能的保證。若 Docker 官方支援範圍變更,應重新核對版本並重跑驗證。
主機端映像建置:用最小工作流程測通命令與產物
如何在 macOS 自託管 runner 上建置 Docker 映像?
先用不含額外服務依賴的最小 Dockerfile,驗證工作流程能否從 runner 主機執行 Docker 命令。依序完成以下操作:
- 建立測試工作目錄與最小 Dockerfile。 只加入必要建置內容,避免一開始就引入資料庫、外部服務或複雜的多階段流程。
- 在 runner 主機確認 CLI 可用。 以工作流程 shell 執行
docker version,確認命令可執行,並檢查 client 與 daemon 是否能正常通訊。 - 執行最小建置。 以
docker buildx build --tag example/app:ci --load .測試主機端建置與本機載入。--load等輸出選項的行為應依 Buildx 文件核對;要推送映像時,則依工作流程選擇相應的輸出方式。Buildx 建置命令參數文件說明可使用的建置參數。 - 驗證輸出,而非只看指令結束。 在 runner 上檢查映像是否存在,並確認後續步驟能讀取預期標籤。若 CI 要推送產物,使用工作流程所需的憑據完成登入與推送測試。
- 記錄失敗位置。 分別記錄安裝、daemon 連線、建置、產物輸出或推送在哪一步失敗,方便判斷問題來自主機環境、權限還是工作流程設定。
若建置目標包含不同處理器架構,不要把一次本機成功當成跨架構成功。Buildx 的多平台建置還涉及目標平台與建置環境條件;先依官方指南配置,再在實際目標環境驗證產物。Docker 多平台建置文件可作為平台設定的依據。本文不預設特定 Mac 配置的建置速度,也不承諾跨架構結果。
工作流程分流:Mac 主機步驟與 Linux 容器工作分開
Mac runner 可以執行 Docker container action 嗎?
不能把 Mac runner 當成執行 Docker container actions 或 service containers 的 Linux runner 替代品。GitHub 官方 runner 文件對這類自託管工作列出 Linux 要求。即使 Docker Desktop 已啟動、docker buildx 建置成功,也不會改變工作流程執行容器 action 或 service container 的 runner 作業系統要求。
更穩妥的拆法,是讓需要 macOS 的主機端 shell 工作留在 Mac,將容器 action 或 service container 所在工作派到 Linux。工作之間可依賴前一個工作的輸出或建置產物,但要確認產物格式和後續步驟相容。runner 標籤應根據 job 的實際依賴設定,而不是只根據「有沒有 Docker」。
典型情況是:工作流程需要先在 macOS 主機執行專用腳本,再建置 Docker 映像。此時 Mac runner 可執行前述主機端流程;若後續工作依賴 service container,該工作就應安排在 Linux runner。這樣能把作業系統限制放在路由階段處理,而不是等 job 執行到一半才失敗。
維護責任:憑據、快取與更新都要有回復流程
自託管 runner 不是註冊完成就能放著不管。團隊需要負責 runner 是否在線、哪些工作流程可使用、敏感憑據如何提供、舊映像和建置快取如何清理,以及 runner 軟體和 Docker Desktop 如何更新。任何一項沒有明確負責人,都可能讓建置失敗後無法快速定位原因,或讓不必要的資料長期留在主機。
正式接入前,先用非生產工作流程演練失敗重試和清理:確認重跑不會誤用舊產物;測試取消工作後,暫存資料與映像如何處理;驗證憑據不會以明文寫入日誌。接著記錄 macOS、Docker Desktop、runner 與工作流程設定的變更,回歸問題發生時才有依據比較差異。
租用 Mac 執行 Docker CI 前要核對什麼?
除 Docker Desktop 的系統支援與授權外,還要確認目標主機是否可完成虛擬化相關啟動、安裝所需權限由誰處理,以及 runner 的線上狀態與憑據由誰維護。把這些條件放進部署驗收表,再以實際工作流程驗證;不能只根據「提供 Mac 主機」推定 Docker Desktop 一定可用。
只用 Linux runner 的團隊,通常不需要為 Docker 映像建置額外引入 Mac;需要在同一個 CI 流程中執行 macOS 主機步驟的團隊,則可把 Mac 作為專用環境,但仍要把容器 action 與 service container 留給 Linux。若考慮租用 Mac,可先比較ProxyMac 方案資訊,並將 Docker Desktop 的支援、授權和目標主機實測結果納入決策。
沿用單一 Linux 環境的 CI,可能無法執行必須在 macOS 主機完成的步驟;把全部工作改放 Mac,又會碰上容器 action 和 service container 的 Linux 限制,並增加權限與維護負擔。若團隊需要臨時的 Mac CI 測試環境,租用 ProxyMac 可先用真實工作流程驗證主機端 Docker 建置,再決定哪些工作保留在 Mac、哪些交回 Linux。若是長期穩定的高負載工作,或必須直接連接特定實體介面,則應先評估自購主機或其他符合條件的環境;租用並非所有 CI 情境的最佳選擇。