摘要：遠端 Mac與共享 Runner的 PHP 流水線：跨境、驗證、鎖定檔三瓶頸；Packagist／鏡像／私服鏈與 GitLab CI 併發、代理、二四八秒退避；附範例與快取鍵、FAQ。延伸Gradle／Maven、Go、鏡像文；說明、購買免登入。
場景與瓶頸：跨境拉取逾時、身分驗證與鎖定檔一致性
跨境逾時拖長下載；驗證未進密文致 Registry 還原不穩；鎖定檔須與僅依鎖定檔安裝一致，勿在線上偷改。按公開／私有占比選鏡像或權限；並存時私服端點前置、官方備援，Runbook 寫清變更上游責任人。
Packagist、境內鏡像與企業私服：鏈式回源對照與可執行設定
下表對照上游型態；網域換核准端點，密文注入敏感欄位。
鏈式回源與指令範例
| 策略 | 適用情境 | 可執行設定方向 |
|---|---|---|
| 官方 Packagist | 合規要求直連上游、延遲可接受 | 維持預設或明確指定官方倉庫網址 |
| 區域鏡像 | 跨境慢、需降低對官方連線次數 | 以全域或專案層級覆寫套件索引與下載來源 |
| 企業私服匯聚 | 內外套件統一快取與審批 | 在 composer 設定中把私服列為優先 repositories |
| GitLab Registry | 套件發佈在同平台專案或群組下 | 新增 composer 型別儲存庫並指向 API 套件路徑 |
# 全域改用區域鏡像（請替換為貴司核准的鏡像根網址）
composer config -g repos.packagist composer https://example-mirror.example.com/
# 專案內優先走 GitLab Package Registry（群組層級示例，請替換網域與群組編號）
composer config repositories.gitlab composer https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/composer/
# 以環境變數注入 Token（勿寫入版控）
# export COMPOSER_AUTH='{"gitlab-token":{"gitlab.example.com":"YOUR_TOKEN"}}'
與 GitLab CI 並行：併發、HTTP 代理與重試退避清單
約定同節點並行安裝上限；代理統一變數與根憑證。流程級重試限次；腳本二四八秒退避、總等待約六十秒；日誌記註冊表主機名。共享節點可串列依賴。
遠端 Mac 快取目錄、環境變數與 CI 快取鍵
掛卷放快取；環境變數指目錄；快取鍵納鎖定檔雜湊；共用層寫清理責任。
# 將快取放到專案旁邊的持久路徑（示例） export COMPOSER_CACHE_DIR="$CI_PROJECT_DIR/.composer-cache" mkdir -p "$COMPOSER_CACHE_DIR" # GitLab CI 快取鍵思路（片段示例，請依實際 YAML 合併） # key: composer-files-$CI_COMMIT_REF_SLUG # paths: [ .composer-cache/ ]
落地步驟清單（建議順序）
1
盤點：分公開與私有來源；鎖定檔入版控並對齊安裝指令。
2
鏡像鏈：私服、鏡像、官方備援排序寫入設定與文件。
3
憑證：密文注入認證資訊並訂輪替週期。
4
快取：固定快取目錄與含鎖定檔雜湊的快取鍵。
5
驗收：冷熱啟比對日誌與磁碟餘裕。
可引用檢查項（寫進 Runbook）
- 鎖定檔：主線須帶鎖定檔；改依賴樹的合併須同步更新鎖定檔。
- 密文：Token 僅放密文或短期變數並標到期日。
- 鏡像：上游網域走核准清單，變更附回滾演練。
常見問題：四零一、速率限制與雜湊校驗失敗
為何一直出現四零一未授權？
核對 Registry 主機名與 Token 範圍、是否過期；確認 GitLab 專案或群組套件權限。
遇到速率限制或連線被拒怎麼辦？
降並行與同機 Pipeline 數、改匯聚或第二鏡像；固定出口並協調配額；重試用指數退避。
安裝時提示雜湊校驗失敗或內容與鎖定檔不符？
對齊工具主版本與外掛；清混用鏡像的快取殘留；在開發端重產鎖定檔，勿在正式線上默默更新鎖定檔。