2026 年前端避坑對照表：
遠端 Mac 上 Biome 與 TypeScript 增量檢查平行 worker、快取與發布前三步驗收
在遠端 Mac或自託管 Runner上，把 Biome 的 lint／format 與 TypeScript 的增量型別檢查（tsc --incremental）疊在同一條流水線，常見坑是快取鍵漏欄位、兩行程搶滿 CPU、tsbuildinfo 路徑漂移致「每次都像全量」。本文以對照表對齊 biome.json 與 tsc，並附Runner／核心綁定速查與 CI/CD 的發布前三步驗收。延伸閱讀：Monorepo 遠端快取、ESLint／Stylelint 修復分支、package.json scripts 預檢。
發布前三步驗收（可貼進 PR 範本）：
- 第一步：
tsc -p . --noEmit（Monorepo 則依各套件腳本）結束代碼 0，且*.tsbuildinfo寫入路徑與tsconfig的incremental／composite一致。 - 第二步：
biome check（或biome ci）結束代碼 0；若與 format 分步，請確認 CI 與本機同一biome.json與同一 Biome 版本。 - 第三步：預覽環境或最小冒煙（路由、授權、關鍵 API）通過後再晉級正式環境；可與 部署前冒煙 串聯。
遠端節點磁碟延遲會放大 tsc 讀取專案參照與 .d.ts 的 I/O；請在 CI 日誌區分「快取命中」與冷啟全量，並讓步驟一寫明預期的 tsBuildInfoFile，以免 paths 與根 tsconfig 在筆電與 Runner 不一致時增量路徑先壞。
01 biome.json 與 tsc --incremental 對照表
下表用於審查「靜態檢查階段」設定是否成對閉合：Biome 管檔案集合與規則版本，tsc 管型別圖與增量產物。Monorepo 建議每個套件獨立 tsconfig 與明確的 tsbuildinfo 輸出，避免根目錄單點失效；套件圖與快取鍵可對照 SSR 建置併發與記憶體 中的 worker 思路。
| 維度 | Biome（biome.json／CLI） | TypeScript（tsconfig ＋ tsc） |
|---|---|---|
| 掃描範圍 | files.include／ignore；CLI 傳入路徑時與設定求交 |
include／exclude；references 多專案時需頂層 tsc -b 或分套件呼叫 |
| 增量開關 | 內部索引與 .biome-cache（升級版號後建議清理） |
"incremental": true；常與 composite 並用；CLI：tsc --incremental（實際行為以 tsconfig 為準） |
| 產物路徑 | 預設專案下 .biome-cache/ |
tsBuildInfoFile 指定 *.tsbuildinfo；預設多在 outDir 旁，需避免被 clean 誤刪或未納入快取 |
| 平行與 worker | Biome 內建多檔平行；可用 --max-diagnostics 控制輸出量 |
tsc 以單行程為主；與 Biome 適合行程級平行，勿指望 tsc 內建多 worker |
| CI 建議指令 | biome ci . 或 biome check --error-on-warnings |
tsc -p tsconfig.json --noEmit 或 tsc -b（專案參照） |
02 平行 worker 與 CPU 核心綁定（macOS）
在 GitHub Actions 自託管或單機多 Job的 遠端 Mac 上，Biome 與 tsc 同時跑容易把 P 核打滿，拖慢同機的 Vite／Webpack 建置。可執行策略如下：
- 流水線分層：lint＋typecheck 一個 job，build＋test 另一個 job，用 needs 串接；比同 job 內盲目
&背景執行更可控。 - 限制併發 Job 數：自託管 Runner 用標籤分組，讓每台機器同時只跑一條重型 workflow。
- CPU 親和（選用）：在 Apple Silicon 上可用
taskpolicy -c maintenance降低背景任務優先序，或為檢查腳本獨立 Runner，避免與jest／vitestworker 爭用；實際以監控為準。 - 執行緒池：若同行程還有 Node 原生依賴，留意
UV_THREADPOOL_SIZE與建置工具的 worker（參見 Tailwind／PostCSS 記憶體與 worker）。
| Runner 情境 | Biome／tsc 排列 | CPU 核心綁定建議 |
|---|---|---|
| 單機單 workflow | 同 job 內先 Biome 再 tsc（快失敗），或兩個獨立 job 平行 | 預留 1～2 核給 I/O 與系統；勿與完整 E2E 同窗全開 |
| M3／M4 以下記憶體吃緊 | Biome 與 tsc序列化較常勝過過度平行 | 檢查類步驟用 maintenance 優先序，建置類保留預設／utility 類 |
| 多 repo 共用一台 Mac | 以 Runner 標籤隔離「靜態檢查」與「完整建置」佇列 | 每台機器同時最多一個 tsc 全量視窗；Biome 可與輕量腳本共用剩餘核 |
03 快取目錄與 CI 快取鍵
下列路徑建議納入 actions/cache 或遠端建置快取，並在 lockfile、Biome 版號、tsconfig 變更時失效：
.biome-cache/- 各套件
*.tsbuildinfo（與tsBuildInfoFile一致） node_modules/.cache（若其他工具與 Biome／tsc 共用機器）
若命中率長期為 0，先檢查是否每次 Job 刪除了 outDir 或把 tsbuildinfo 放在會被 clean 的目錄；再核對 paths 別名是否與本機一致（遠端 Mac 上路徑大小寫敏感）。依賴安裝與鏡像可對照 執行時與鏡像快取。
04 CI/CD 語境下的門禁順序
建議順序：安裝依賴 → Biome（最快失敗）→ tsc → 單元／E2E → 建置產物。如此能在約一至兩分鐘內擋下格式與低階語法問題，再把時間投給昂貴的型別與測試。與 npm／pnpm 稽核並列時，稽核可放在依賴安裝後、編譯前的獨立 job，以免阻塞開發分支的快速回饋。稽核與型別門禁並存時，建議在摘要或 artifacts 保留當次指令列與結束代碼以利追溯。