2026年前端避坑清單：
遠端 Mac 上 Node/npm 多版本管理與 Safari 相容性測試流程
前端與全棧開發者、網站運維與測試在遠端 Mac 上常遇到 Node/npm 版本混亂與僅在 Safari 才出現的 Bug。本文提供決策型避坑清單：含 Node/npm 多版本管理、Safari 與 Playwright 要點、相容性測試流程、常見問題排錯及可執行清單；文末引導至站內博客與購買頁。💻🚀
01 Node/npm 多版本管理方案
在遠端 Mac 上多專案並存時，務必使用版本管理器（nvm 或 fnm）並以 .nvmrc／.node-version 鎖定專案 Node 版本，避免全域 npm 與建置環境不一致。
| 方案 | 適用情境 | 關鍵指令 |
|---|---|---|
| nvm | 需多版本並存、腳本與 CI 共用 | nvm install、nvm use；專案目錄下讀取 .nvmrc |
| fnm | 啟動快、支援 .node-version | fnm install、fnm use；與 nvm 指令對應 |
- 步驟一： SSH 登入遠端 Mac，安裝 nvm 或 fnm 並在 shell 設定中載入。
- 步驟二： 在專案根目錄建立
.nvmrc或.node-version，寫入目標 Node 版本號。 - 步驟三： 進入專案後執行
nvm use或fnm use，再執行npm ci與建置。
02 Safari 測試環境與 Playwright 要點
僅在 Mac 上能跑真實 WebKit/Safari；Windows 無法原生執行 Safari。在遠端 Mac 上安裝 Playwright 後，可執行 WebKit 以覆蓋 Safari 相容性。
安裝：npx playwright install webkit（必要時 --with-deps）。測試可選 headed 或 headless；需真實 Safari 行為時建議在遠端 Mac 上跑 headed。設定 browserName: 'webkit' 即可針對 Safari 情境。
03 相容性測試流程
建議依序執行以下步驟，確保上線前 Node 環境與 Safari 行為均通過。
- 在遠端 Mac 上切換至專案 Node 版本（
nvm use／fnm use），執行npm ci && npm run build。 - 執行 Lint／型別檢查（若有）：
npm run lint、npm run typecheck。 - 安裝並執行 Playwright WebKit 測試：
npx playwright install webkit，再執行專案內 E2E 或 smoke 腳本。 - 檢查關鍵頁面在 WebKit 下是否正常（版面、JS、API 回應）。
- 將上述步驟寫入 CI 或部署前腳本，與遠端 Mac 環境一致。
04 常見問題與排錯
建置或測試失敗時，可依下表對照排查。
| 現象 | 可能原因 | 排錯建議 |
|---|---|---|
| 建置失敗、模組不相容 | Node 版本與 .nvmrc 不一致 | 腳本前顯式執行 nvm use 或 fnm use；確認 node -v 與專案一致 |
| 找不到 npm／npx | PATH 未載入 nvm/fnm | 使用登入 shell 或於腳本內 source nvm/fnm 後再執行 npm |
| Playwright 報錯、瀏覽器未安裝 | WebKit 未安裝或路徑問題 | 執行 npx playwright install webkit，必要時加 --with-deps |
| E2E 逾時 | 逾時過短或服務未就緒 | 提高 E2E 逾時、確認 dev/build 服務已啟動後再跑測試 |
05 避坑清單
發布前建議逐項勾選，減少遠端 Mac 上 Node/npm 與 Safari 相容性問題。
- □ 專案已建立
.nvmrc或.node-version，且 CI 與本機共用。 - □ 每次建置／測試前已執行
nvm use或fnm use。 - □ 使用
npm ci安裝依賴，避免鎖檔與環境不一致。 - □ 遠端 Mac 上已安裝 Playwright WebKit（
npx playwright install webkit）。 - □ 至少一次在 WebKit／Safari 情境下跑過核心流程或 smoke 測試。
06 常見問題 FAQ
遠端 Mac 上如何管理多個 Node/npm 版本？ 使用 nvm 或 fnm，專案根目錄放 .nvmrc 或 .node-version，登入後執行 nvm use／fnm use；CI 與本機讀取同一檔案。
Safari 相容性測試如何執行？ 安裝 Playwright 後執行 npx playwright install webkit；可選 headed 或 headless。僅 Mac 有真實 Safari。
建置或測試失敗常見原因？ Node 與 .nvmrc 不一致、PATH 未載入 nvm/fnm、Playwright 未安裝或逾時。腳本前顯式 nvm use、執行 playwright install 並提高 E2E 逾時。