需要頻繁拉取代碼與依賴的開發者、CI 使用者與跨國團隊，在遠端 Mac 上常因完整 clone 與重複下載拖慢建構。💻 本文提供「對比表＋步驟清單」：為何快取策略影響建構速度、Git shallow clone 與 partial clone 對比與參數、npm/Homebrew 快取配置與 CI 環境複用、三步加速清單與可執行命令、常見失敗場景與排錯，可落地、可複現。
為什麼遠端 Mac 上快取策略影響建構速度
遠端 Mac 建構節點每次 job 若都做完整 git clone與從零 npm install，會耗費大量時間與頻寬，跨區網路延遲更會放大問題。💡 三點關鍵：① 程式碼體積：完整歷史可能數 GB，shallow 或 partial clone 可縮至數十 MB；② 依賴重複下載：未複用快取時，每次 CI 都重新拉取 node_modules / Homebrew；③ 跨國團隊：遠端節點與 registry 距離影響延遲，快取與鏡像可顯著縮短建構時間。
Git shallow clone 與 partial clone 對比與參數
| 方式 | 指令／參數 | 適用場景 | 注意事項 |
|---|---|---|---|
| Shallow clone | git clone --depth=1 <url> | CI 只需最新 commit、不需歷史 | 後續無法直接 push 全部分支；需歷史時可 git fetch --depth=... 加深 |
| Partial clone（blob:none） | git clone --filter=blob:none <url> | 大倉庫、需部分歷史，按需拉取 blob | Git 2.22+；首次仍比 shallow 慢，後續 checkout 時才拉 blob |
| 完整 clone | git clone <url> | 需完整歷史、bisect、多分支開發 | 體積與時間最大，CI 一般不建議 |
實戰建議：CI 預設使用 --depth=1；若需指定分支可加 --branch <name>。大 monorepo 可評估 --filter=blob:none 搭配 --single-branch。
npm / Homebrew 快取配置與 CI 環境複用
npm：設定 cache 目錄並在 CI 中掛載為快取層，例如 npm config set cache $CI_CACHE/npm；或使用 npm ci 搭配 package-lock.json 確保可重現。CI 步驟中可「還原快取 → npm ci → 儲存快取」以複用 node_modules 或至少 ~/.npm。
Homebrew：HOMEBREW_CACHE 指向共用目錄，CI 可將該目錄掛載為 cache；安裝前 brew update 可依策略節流（例如僅在 schedule 時更新）。
三步加速清單與可執行命令
1
Git： 使用 shallow 或 partial clone，減少拉取體積與時間。
git clone --depth=1 --branch main https://github.com/org/repo.git .
2
npm： 掛載 CI 快取目錄並使用 npm ci。
npm config set cache $CI_PROJECT_DIR/.npm_cache npm ci
3
建構： 在還原快取後執行 build，並視需求儲存快取供下次 job 使用。
npm run build # 或您的建構指令
常見失敗場景與排錯
- Shallow 導致歷史不足： 建構或腳本需要更多 commit 時，使用
git fetch --depth=100加深，或改用--filter=blob:none。 - npm 快取失效或 lock 不一致： 確保 CI 使用
package-lock.json且不略過npm ci；快取 key 建議含lockfile雜湊。 - 網路逾時／registry 慢： 遠端 Mac 節點選靠近 registry 的區域，或設定 npm/brew 鏡像與
fetch-retries。
可引用要點
- CI 預設使用
git clone --depth=1可大幅縮短拉取時間；大倉庫可評估--filter=blob:none。 - npm 快取目錄與
npm ci搭配 CI 快取層，可避免每次從頭下載依賴。 - 遠端 Mac 建構節點選擇靠近 registry 的區域、搭配鏡像與重試，可降低跨區延遲與失敗率。