2026 年前端避坑對照表：
遠端 Mac 上 Cypress、WebKit 與 Safari
團隊租用遠端 Mac跑 Apple 原生瀏覽器，卻常把 Cypress WebKit 的綠燈當成使用者端 Safari已驗證——中間的落差會帶著版型與媒體 bug 上線，而全程錄影又會塞爆共用 SSD。下文整理適用場景、與真 Safari 的對照表、二進位快取與安裝參數、video／screenshot 開關、worker 與重試閾值驗收，以及發布前三步。延伸閱讀：Vitest／jsdom 與 WebKit 矩陣、Playwright 與 Safari 兼容性、技術見解全文。
01 Cypress＋WebKit 適用場景
當團隊已深度使用 Cypress API，且需要在同一台 Apple Silicon 映像上兼跑 Chromium 與 WebKit 管線時，Cypress WebKit 適合用來覆蓋穩定選擇器、長度中等的 SPA 回歸。它能較快發現 WebKit 特有的 DOM／事件邊角，並與既有 spec 共用斷言風格。
不應單獨依賴它驗證以影片為核心的產品、嚴格跨站儲存敘事，或 WebGL／Canvas 比重高的介面——自動化綁定的 WebKit 與分析後台裡使用者實際的 Safari 組建仍可能分歧。建議讓 Cypress 負責「快且可重複」的 WebKit 回歸，並在同一主機保留 Safari.app 的冒煙或第二套腳本；單元層與 jsdom 的覆蓋邊界可對照篇首 Vitest／WebKit 矩陣內鏈。
02 與真實 Safari 差異對照表
誤信風險：WebKit 全綠仍可能漏掉 ITP、低耗電模式與部分轉碼路徑。成本風險：全程錄影在共用 Mac mini 叢集上會快速吃滿磁碟。流程風險：無上限重試會掩蓋薄片。下表供規劃與評審使用；Cypress WebKit 為 Cypress 綁定的引擎，Safari.app 為 Dock 上的系統瀏覽器。
| 面向 | Cypress WebKit（遠端 Mac） | Safari.app（同一主機） | 實務結論 |
|---|---|---|---|
| 引擎對齊 | 由 Cypress 釘選的自動化 WebKit 套件 | 系統 Safari，更新節奏獨立 | 大版本盡量對齊主力使用者分群 |
| GPU 與合成 | 仍走 Metal，但受 headed／headful 設定驅動 | 含完整使用者工作階段與視窗伺服器效果 | 自動化通過後仍應手檢 HDR、全螢幕影片與 canvas |
| 自動播放與媒體 | 接近 WebKit，但與手動瀏覽情境不盡相同 | 手勢、低耗電、背景分頁政策皆生效 | OTT、直播、會議流至少保留一次真人播放路徑 |
| ITP 與 Cookie | 會走到 WebKit 儲存相關程式碼路徑 | 含完整跨站追蹤規則出貨組態 | 模擬 ITP 重置後登入持久化須在 Safari 再驗 |
03 遠端 Mac 上瀏覽器二進位快取路徑與安裝參數
預設快取位於 ~/Library/Caches/Cypress。在共用遠端 Mac 池請設定環境變數 CYPRESS_CACHE_FOLDER 指向持久磁碟；映像烘焙階段執行 npx cypress install，平行 spec 前先斷言該目錄存在且權限正確。日誌應含 Cypress 版本、WebKit 路徑與剩餘空間；若開啟錄影，建議維持約兩百 GB可用空間並排程清理。產物與日誌分診流程可與 OpenClaw／CI 的 E2E 回歸摘要管線並行導入（見技術見解內「E2E 日誌分診」主題）。
安裝／快取驗收清單
- 釘選套件版本、lockfile 與 CI 快取鍵；多租戶共用主機時隔離各租戶快取目錄。
- 以單支 spec 在開頭記錄
cy.browser家族與版本，供稽核儀表板比對。 - 執行
npx cypress verify，安裝不完整時讓工作立即失敗，避免跑到一半才缺二進位。 - 產物路徑以
GITHUB_SHA（或同等提交鍵）分桶，避免重跑覆寫影片。 - 每週排程刪除超過保留天數的錄影檔（建議共享主機七天內）。
04 video／screenshot 開關
建議 PR 管線將 video 設為 false；僅在 main、夜間或專用 WebKit 任務開啟錄影。維持 screenshotOnRunFailure: true 以便快速定位。若短期除錯需要，可用環境變數在單支 spec切換錄影，避免全域長開。錄影是 Mac 叢集上的課稅資源——檔名務必帶提交 SHA，並與保留政策一起文件化。
05 平行 worker 與重試閾值
平行度取決於機器數與實體核心，而非無限執行緒：錄影開啟時，可從約每八顆效能核心對應一個 WebKit 工作負載開始調校。retries.runMode 建議 main 上 WebKit 設為一次、PR 設為零；若單一迭代內超過約百分之二的執行因重試才轉綠，應優先修復等待條件與測試資料，而非調高閾值。
| 驗收項 | 參數／觀測點 | 通過準則 |
|---|---|---|
| 併發 | 平行機器數 vs 實體核心 | 穩態 WebKit 負載下 CPU 未長期高於約九成 |
| 重試 | runMode 重試次數 |
每次「靠重試救回」須有負責人與議題連結 |
| 產物 | 錄影開或關 | PR 預設關；main 建議僅失敗時保留完整影片 |
| 逾時 | defaultCommandTimeout |
僅針對已知慢指令上調，避免全域加倍 |
06 發布前三步驗收
以下三步須共用同一組建產物與環境清單（Node、Cypress、macOS 小版本、快取路徑），再允許打發布標籤。
- 第一步：對齊 Cypress、Node、macOS 小版本；預熱
CYPRESS_CACHE_FOLDER並留存安裝校驗日誌。 - 第二步：依本分支層級核對錄影、截圖、平行 worker 與重試設定，對照上一節驗收表逐項勾選。
- 第三步：在同一台 Mac 上以 Safari.app 執行 P0 流程（含冷啟動與背景分頁），結果附於工單或變更單。
共享主機建議保留約兩百 GB可用空間、單迭代重試薄片比例上限約百分之二、錄影保留約七天並自動清理。
首頁 · 購買／租用 · 幫助中心 · 技術見解 · Node／npm 與 Safari 清單 · Playwright Safari 測試