Yarn Berry PnP 與 classic node_modules 對照表（決策用）
若你的搜尋意圖是「跨境延遲下要不要開 PnP」「registry 鏡像會不會搞壞 checksum」「併發安裝會不會打爆 429」，請先用下表在架構會議上對齊語意，再落到參數與驗收。
| 維度 | Yarn Berry（PnP／ZipFS） | classic node_modules |
|---|---|---|
| 磁碟與 inode | 預設不展開海量小檔；.yarn/cache 可集中快取，利於 APFS 上控水位 | 大量小檔與深路徑；跨境冷啟時寫入與 metadata 成本高 |
| 跨境 HTTP 形態 | 偏向少量 tarball／快取命中；miss 時仍受 RTT 影響但重試面較集中 | 高併發小物件與解壓；易觸發 registry 頻寬與連線數上限 |
| 與 iOS／原生工具鏈 | 需確認 Metro、腳本、部分 CLI 是否支援；可能要 nodeLinker 或補丁 | 相容性最寬鬆；與既有 Pod 腳本、絕對路徑假設最合拍 |
| lockfile 真理來源 | yarn.lock＋Berry 設定；CI 建議 yarn install --immutable | 同上，但若混用 npm 子專案需防雙 lock 漂移 |
| 快取策略 | enableGlobalCache、compressionLevel、自架 npmRegistryServer 鏡像 | 常用 npm_config_cache／CI tarball 還原 node_modules；鏡像與 token 規則須與 npm 一致 |
跨境延遲下兩種模式耗時對比
2026 年主流 Runner 已普遍落在 Apple Silicon 與 Node 22 LTS 組合：CPU 解壓與 TLS 已不是唯一瓶頸，跨地域 RTT 與 registry 連線數 才是變異來源。PnP 在「無 tarball 快取、全量重抓」時，單次安裝常因請求次數較少而略優於首次展開 node_modules；但若你已把 .yarn/cache 或 node_modules tarball 當作工作區種子，兩者差距會收斂到「誰的種子更新成本更低」。實務上請用同一臺 遠端 Mac CI 固定錄三段計時：僅 lockfile 變更、中等量依賴升級、全清快取冷啟，再選擇要優化「種子大小」還是「請求形態」。
registry 鏡像與 Yarn／npm 安裝參數
鏡像端點請與資安確認是否允許透明代理；若僅能企業內網 registry，請把 yarnPath、Corepack 與實際執行的 yarn 版本鎖進 repo，避免「本機 Berry、CI 誤用全域 classic」這類漂移。
# —— Yarn Berry（片段；完整請併入 .yarnrc.yml）—— # nodeLinker: pnp | node-modules # npmRegistryServer: "https://registry.npmmirror.com" # networkConcurrency: 8 # compressionLevel: mixed # enableGlobalCache: true # —— 環境變數（CI 密文注入 token；勿寫入 repo）—— export YARN_NETWORK_TIMEOUT=120000 export COREPACK_ENABLE_DOWNLOAD_PROMPT=0 # npm 生態相容腳本仍讀： export NPM_CONFIG_FETCH_RETRIES=3 export NPM_CONFIG_FETCH_RETRY_MINTIMEOUT=20000 export NPM_CONFIG_FETCH_RETRY_MAXTIMEOUT=120000 # 可選：HTTP(S)_PROXY 走固定出口，便於白名單與審計 # —— 安裝命令（驗收向）—— yarn install --immutable --check-cache
GitHub Packages／npm 雙源認證與 token 輪換
雙源時常見錯誤是 401／E404：scope 指到錯的 registry，或 _authToken 只寫在其中一個 host。建議在 CI 以分開密文管理 NPM_TOKEN（npmjs）與 GITHUB_TOKEN／細粒度 PAT（read:packages），並在安裝步驟前寫入最小權限的 .npmrc（或由 actions/setup-node／等價步驟產生）。Token 輪換：排程到期前先在 staging Runner 驗證 lockfile 與鏡像路徑；輪換當日保留舊 token 灰度一小時窗口，並監控 401 率。若組織已上 OIDC 發佈 npm provenance，可同步評估減少長效 PAT 面積。
CI 並行度與磁碟水位閾值
同一臺 遠端 Mac 若併跑多條 Pipeline，networkConcurrency 與 YARN_PARALLELISM 的乘積會直接決定出站連線數。Apple Silicon 單機頻寬飽和後，再拉高併發只會換來 429 與重試風暴。磁碟方面，請在安裝前以腳本讀 df -h：可用空間低於約 15%（或絕對值低於你們的 monorepo 種子大小）時改走「降併發＋清暫存＋失敗即短路」，避免把整段 Xcode 構建拖死在半套 node_modules。
- networkConcurrency：跨境起點約 4–8；內網鏡像可階梯升到 12–16 並觀察 429。
- YARN_PARALLELISM：對齊 vCPU 的 0.5–1 倍，且不高於同機 Pipeline 數 × 單線併發上限。
- df 水位：警告 85%、硬停止安裝 90%（依 APFS 保留空間策略調整）。
失敗重試與 lockfile 一致性驗收
流程級重試建議仍採 二／四／八秒退避、最多三次，但僅限網路類錯誤；yarn install --immutable 若報「lockfile 需更新」，屬一致性問題，重試無效，應回到開發機修正後提交。驗收清單：安裝後對關鍵 workspace 執行單測或 typecheck，必要時跑 yarn explain peer-requirements 掃描隱性漂移；iOS 側再觸發一次最小 xcodebuild -list 或單一 scheme 編譯，確認腳本讀到的模組解析路徑無誤。
FAQ
monorepo 同時有 React Native 與原生 iOS 外掛，該選 PnP 還是 node_modules？
若大量工具鏈仍假設實體 node_modules（舊版 Metro、部分原生腳本），優先 classic 或 nodeLinker: node-modules；若已全鏈支援 ZipFS／SDK 補丁且願維護 .yarnrc.yml，PnP 可顯著減少跨境 I／O 與磁碟占用。折衷為 node-modules 加全域快取目錄與鏡像。
GitHub Packages 與 npmjs 雙源時，401 或 E404 最常踩哪幾點？
scope 對錯 registry（@org:registry=）、token 僅寫入 //npm.pkg.github.com/ 或 //registry.npmjs.org/ 其中一行導致另一源未授權、以及過期 PAT。建議分開密文變數並在安裝前以 npm ping／yarn npm info 探測；輪換時同步檢查 lockfile 內 resolved 是否仍指向預期端點。
yarn install --immutable 失敗顯示 lockfile 需變更，能直接在 CI 改嗎？
不應在 CI 靜默改 lockfile：代表本機與 CI 解析器或 registry 鏡像不一致。應在開發機重現、提交更新後的 yarn.lock，並檢查是否誤用不同 Yarn 版本或鏡像劫持。流程級可對網路步驟二／四／八秒重試，但 immutable 失敗本身不是重試可修。
總結：2026 年在 遠端 Mac CI 上選 Yarn Berry PnP 或 classic node_modules，本質是在「併發安裝 形態、磁碟水位、與 iOS 工具鏈相容」之間取捨；再叠上 registry 鏡像 與 GitHub Packages／npm 雙源認證 政策即可定案。若你希望把流水線綁在固定地域、固定規格的 Apple Silicon 節點上反覆校準上述閾值，歡迎先到 定價方案 比較套餐，或直接至 購買頁 選擇合適租期試跑；操作細節也可查 說明中心 與 繁中首頁。