DevOps / CI/CD

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

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 命令。依序完成以下操作:

  1. 建立測試工作目錄與最小 Dockerfile。 只加入必要建置內容,避免一開始就引入資料庫、外部服務或複雜的多階段流程。
  2. 在 runner 主機確認 CLI 可用。 以工作流程 shell 執行 docker version,確認命令可執行,並檢查 client 與 daemon 是否能正常通訊。
  3. 執行最小建置。 以 docker buildx build --tag example/app:ci --load . 測試主機端建置與本機載入。--load 等輸出選項的行為應依 Buildx 文件核對;要推送映像時,則依工作流程選擇相應的輸出方式。Buildx 建置命令參數文件說明可使用的建置參數。
  4. 驗證輸出,而非只看指令結束。 在 runner 上檢查映像是否存在,並確認後續步驟能讀取預期標籤。若 CI 要推送產物,使用工作流程所需的憑據完成登入與推送測試。
  5. 記錄失敗位置。 分別記錄安裝、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 情境的最佳選擇。

為 CI 流程配置專屬雲端 Mac

透過 ProxyMac 租用獨享 Mac mini M4 實體節點,為自託管 runner 提供完整 macOS 執行環境。
支援 SSH、VNC 與瀏覽器連線,方便團隊部署、管理及排查建置工作。