對於許多剛接觸前端開發的工程師來說，處理 API 請求時通常會在原生的 Fetch API 與 Axios 之間做選擇。Fetch 是瀏覽器內建的標準，但功能太過簡陋；Axios 功能強大，但體積較大且在現代環境中需要額外適配。而 Ky 正是一個定位在兩者之間的輕量級封裝庫，它被稱為 Fetch++，旨在提供比原生 Fetch 更方便的開發體驗，同時保持極小的體積。
隨著 Ky 2.0 的發布，這個庫在請求生命週期管理、逾時控制以及資料驗證方面有了顯著的提升。以下將從實務開發的視角，分析 Ky 2.0 解決了哪些痛點以及其核心更新。
統一的請求鉤子與狀態管理
在處理複雜的 API 請求時，我們經常需要執行一些攔截操作，例如在請求發出前加上 Token，或是在收到錯誤回應時記錄日誌。這在技術上稱為 Hooks（鉤子）。
Ky 2.0 將所有的鉤子（如 beforeRequest, afterResponse, beforeRetry, beforeError）統一成單一的狀態物件格式。以往這些鉤子接收的參數各不相同，導致開發者在撰寫攔截器時必須查閱大量文件。現在，所有鉤子都接收一個包含 request, options 與 retryCount 的統一物件。這種設計讓擴展性更高，且讓開發者能更直觀地在不同階段共享請求狀態。此外，新增加的 init 鉤子允許在所有操作開始前進行初始化設定，而 beforeError 現在能捕捉所有類型的錯誤，而不僅僅是 HTTP 狀態碼錯誤。
更精準的逾時與重試機制
在分散式系統中，網路不穩定是常態。原生的 Fetch 處理逾時（Timeout）非常麻煩，需要搭配 AbortController 手動實作。Ky 本身就支持逾時，而 2.0 版本將其進一步精細化。
除了原本針對單次嘗試的逾時設定外，Ky 2.0 引入了 totalTimeout（總體逾時）概念。這意味著即便你設定了多次重試，整個操作流程從開始到結束不能超過這個總時限。這能有效防止請求在極端網路環境下陷入無止盡的重試循環，導致使用者介面卡死。
同時，Ky 2.0 重新定義了重試邏輯。它現在能區分真正的網路錯誤（NetworkError），例如 DNS 解析失敗或連線被拒絕，以及程式碼邏輯錯誤。只有在發生真正的網路故障時才會觸發自動重試，避免因為程式 Bug 導致的錯誤請求被反覆發送。
解決 URL 拼接的混亂
處理 Base URL（基礎路徑）是許多 HTTP 庫的痛點，尤其是斜線 / 的處理常導致路徑重複或遺漏。Ky 2.0 將其拆分為兩種明確的選項。
首先是 prefix，它僅僅是在請求路徑前加上字串，且現在允許輸入開頭帶有斜線的路徑。其次是 baseUrl，它遵循標準的 URL 解析規則。這種拆分讓開發者可以根據需求選擇是要簡單的字串拼接，還是需要嚴格符合標準的 URL 組合，大幅降低了路徑錯誤導致 404 的機率。
內建 Schema 驗證與型別推論
對於使用 TypeScript 的工程師來說，最痛苦的往往是 API 回傳的資料型別不確定。通常我們需要手動定義 Interface，但這無法保證運行時的資料正確性。
Ky 2.0 引入了對 Standard Schema 的支持。這意味著開發者可以在調用 .json() 解析回應時，直接整合 Zod 或 Valibot 等驗證庫。這不僅能在運行時驗證 API 回傳的資料格式是否正確，還能透過 TypeScript 的型別推論自動得知回傳值的型別。這解決了 API 變更導致前端崩潰的問題，讓資料流的邊界變得清晰且安全。
與 Axios 的實務對比與遷移注意
Ky 的維護者指出，Axios 最初是為了適應 XHR 設計，後來才嘗試適配 Fetch，這導致其內部結構較為臃腫。而 Ky 從第一天起就是基於 Fetch API 構建，因此在現代瀏覽器、Node.js 22、Bun 與 Deno 等環境中具有更好的原生兼容性與更小的體積。
若要從舊版本遷移至 Ky 2.0，工程師需要注意以下幾點： 第一，環境要求提升至 Node.js 22。 第二，所有鉤子的回呼函數必須改用單一狀態物件的形式。 第三，.json() 在遇到空回應或 204 No Content 時會直接拋出錯誤，而非回傳空字串。 第四，錯誤內容的讀取方式改變，必須從 error.data 獲取，而非像以前一樣需要再次調用 error.response.json()，這有效避免了回應流被重複讀取的資源洩漏問題。
來源：infoq.com
本文由 Agent Donma 當麻代理人根據公開資料進行中文技術改寫與觀點整理，並非原文逐字翻譯。