Vercel 在 2026 年 11 月 2 日宣布所有專案都可使用 vercel.toml。官方表示它支援與 vercel.json 相同的設定屬性，優點是可加入註解，且巢狀設定能以 TOML table 呈現得較平坦。這是新增設定格式，不是要求所有既有專案遷移；原本能正常部署的 vercel.json 或 vercel.ts 不會因公告而失效。

最重要的限制是每個專案只能使用一個 project configuration file：vercel.toml、vercel.json 或 vercel.ts 三選一。不能在遷移期間把兩份檔案都留在主分支，期待 Vercel 自動合併。若設定同時散落在 Dashboard 與 repository，也要先查清楚哪些值由檔案覆寫、哪些仍由平台設定控制，否則單純轉換語法不會消除環境漂移。

三種格式該怎麼選

vercel.json 適合設定短、團隊熟悉 JSON、且現有驗證工具完整的專案。它沒有註解，但格式普遍，許多編輯器與自動化工具都能直接處理。只為了追新格式而轉檔，會增加一次部署變更，卻未必改善維護成本。

vercel.toml 適合需要在設定旁留下原因、服務數量較多，或 TOML 已是團隊主要基礎設施設定格式的專案。Vercel 公告用 Services 為例，在 [services.frontend]、[services.backend] 下分別設定 root 與 entrypoint，再以 rewrites 導向不同服務。這種結構對多服務 repository 較容易閱讀，但語法更好讀不代表架構自動正確；路由優先順序、服務根目錄與 fallback 仍需逐一測試。

vercel.ts 則是程式化設定，適合確實需要在 build time 計算值的情境。它能使用 TypeScript 與環境資訊動態產生 configuration，但也把單純設定變成可執行程式，審查時要考慮依賴、錯誤處理與可重現性。若只是想寫註解，不需要因此升級到動態設定；TOML 已能解決這個需求。

遷移前先建立設定清單

依 Vercel Project Configuration 文件，檔案可控制 build command、framework、functions、headers、redirects、rewrites、images、regions、crons 等屬性。遷移前把現有檔案每個 key 列成清單，特別標記陣列、巢狀物件、正規表示式、含特殊字元的字串與環境相關值。不要憑肉眼改完就刪除舊檔。

接著列出 Dashboard 內的 framework preset、root directory、install/build command、output directory、Node.js version、環境變數、Git 設定、Deployment Protection 與 domain。不是每個 Dashboard 選項都屬於 project configuration schema；不要為了「設定即程式碼」自行猜測未被官方支援的 TOML key。

正式轉換時，使用官方 schema https://openapi.vercel.sh/vercel.json，並逐項比對型別。TOML 的 array of tables、inline table 與字串跳脫方式和 JSON 不同，尤其 redirects、rewrites、headers 等規則常是陣列，最容易在機械轉換中改變結構。轉完後只在遷移分支保留一份候選設定，避免平台讀到多個檔案而無法判斷。

Preview 部署要驗證行為，不只驗證能建置

先建立 Preview deployment，比對轉換前後的 framework detection、install command、build log、輸出目錄與 functions 清單。網站能回首頁不代表設定等價；還要測試 redirects 的狀態碼與 query string、rewrites 的目的地、custom headers、clean URLs、trailing slash、圖片最佳化、cron 路徑，以及不同 region 的 function 行為。

多服務專案應為每個 service 建立健康檢查，驗證前端與 API 的直接路徑，也測試 rewrite 重疊時的優先順序。若 catch-all 規則太早匹配，API 可能被送到前端；若 backend entrypoint 或 root 寫錯，部分頁面可能正常，只有動態請求失敗。驗收紀錄應保存部署 URL、commit、規則輸入與預期輸出，方便回歸。

團隊也要確認本機與 CI 使用的 Vercel CLI 版本能理解新格式。若舊版工具只認得 vercel.json，雲端 Preview 成功而本機 vercel dev 或檢查腳本失敗，開發流程仍不完整。升級工具時鎖定版本，先在測試分支執行，不要把設定格式與 CLI 大版本更新混成一個無法定位問題的變更。

安全上線與回滾方式

上線前先保留舊 vercel.json 的最後可用 commit，而不是在同一 commit 留兩份檔案。完成 Preview 驗收後，再以單一 PR 同時加入 vercel.toml、刪除舊設定，並附上逐項對照表。Production deployment 後檢查核心路徑、函式錯誤率與 redirect 迴圈；若有差異，回滾整個 commit，恢復上一份唯一設定檔。

我的選擇是：短小且穩定的 JSON 不必遷移；需要註解或多服務分段時，TOML 值得在有完整 Preview 測試的前提下導入；真的需要動態計算才使用 TypeScript。格式不是目的，讓部署規則可審查、環境可重建、失敗能快速回滾，才是這次新增選項帶來的實際價值。