從 node-fetch 到 Web Fetchcloudflare-typescript 新版本平滑遷移完整指南【免費下載鏈接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API項目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript如果你正在使用cloudflare-typescriptCloudflare 官方 TypeScript SDK調用 Cloudflare API那么從node-fetch切換到內置Web Fetch的新版本升級就是繞不開的一步。本文是一份面向新手的遷移指南零依賴、自帶一鍵遷移命令按步驟走即可完成平滑升級。一、為什么這次升級值得動手新版 SDK 最大的變化是徹底移除了node-fetch依賴改為使用運行環境內置的 WebfetchAPI實現了零運行時依賴可在 package.json 中看到dependencies為空對象。這帶來了三個直接好處變化點舊版本新版本依賴數量依賴 node-fetch零依賴運行環境主要面向 Node.jsNode 20、Deno、Bun、Cloudflare Workers、瀏覽器通用響應類型Node 專有 Stream/Headers標準 WebReadableStream、Headers遷移工具無官方migrate命令一鍵改代碼二、升級前準備最低環境要求動手前先確認你的工具鏈滿足最低版本要求詳見 MIGRATION.md工具最低版本Node.js20 LTSTypeScript4.9Jest28升級包本身很簡單npm install cloudflare 建議先在功能分支上操作配合 Git 提交方便隨時對比migrate工具的改動。三、最快上手步驟官方 migrate 一鍵遷移命令官方提供了遷移 CLI會自動掃描并改寫你的代碼。推薦先預覽、再應用的兩步走# 第 1 步只預覽改動不寫盤安全試跑 ./node_modules/.bin/cloudflare migrate ./your/src/folders --dry # 第 2 步確認無誤后正式應用 ./node_modules/.bin/cloudflare migrate ./your/src/folders絕大多數項目跑完這兩步就能完成 80% 的遷移工作。剩下的少數場景交給下面的破壞性變更清單逐項排查。四、必須知道的 6 個破壞性變更附前后對比1.asResponse/withResponse返回標準 Web 類型如果你曾對響應做流式處理body現在不再是 Node 的Readable而是 WebReadableStreamAPIError.headers也變成了 WebHeaders實例// 遷移后寫法 import { Readable } from node:stream; const res await client.example.retrieve(string/with/slash).asResponse(); Readable.fromWeb(res.body).pipe(process.stdout);2. 多路徑參數改為命名參數為避免把多個 ID 傳錯順序除最后一個外均需以對象形式命名傳入// Before client.parents.children.retrieve(p_123, c_456); // After client.parents.children.retrieve(c_456, { parent_id: p_123 });完整受影響方法列表收錄在 MIGRATION.md 的折疊章節中排查時可對照查閱。3. 路徑參數默認自動編碼SDK 現在會自動對路徑參數做 URI 編碼請刪掉手寫的encodeURIComponent- client.example.retrieve(encodeURIComponent(string/with/slash)) client.example.retrieve(string/with/slash)4. 請求體必須傳對象端點若接收數組等非對象請求體需要包一層屬性傳入// Before client.example.create([{ name: name }, { name: name }]); // After client.example.create({ items: [{ name: name }, { name: name }] });5.httpAgent移除改用fetchOptions內置 fetch 不支持node:http的 Agent代理配置改為平臺相關的fetchOptionsimport * as undici from undici; const client new Cloudflare({ fetchOptions: { dispatcher: new undici.ProxyAgent(process.env.PROXY_URL), }, });Bun、Deno 的代理寫法略有不同參考 README.md 中Configuring proxies一節的示例即可。6. 導入路徑與內部 API 調整舊寫法新寫法import cloudflare/errorimport cloudflare/core/errorpagination、resource、uploads同理import { APIClient } from cloudflare/coreimport { BaseCloudflare } from cloudflare/clientCloudflare.fileFromPath(...)fs.createReadStream(...)Bun 可用Bun.fileimport cloudflare/shims/web已刪除改為正確配置全局類型cloudflare/src/*cloudflare/*?? 特別注意自動分頁的for await ... of語法不受影響手動分頁則簡化為page.nextPageRequestOptions()一個方法替代原先的nextPageParams()/nextPageInfo()。五、TypeScript 報類型錯誤按運行環境配置升級后若出現Request、Response、Headers相關類型報錯通常是全局類型未配置。對照 MIGRATION.md 的TypeScript troubleshooting章節運行環境tsconfig.json關鍵配置需安裝的類型包Node.jstarget: ES2018建議 ES2020types/node 20Cloudflare Workerstypes: [cloudflare/workers-types]cloudflare/workers-typesBuntarget: ES2018types/bun 1.2.0瀏覽器lib: [DOM, DOM.Iterable, ES2018]無六、升級自檢清單 ?遷移完成后用這份清單快速驗收Node.js ≥ 20、TypeScript ≥ 4.9已執行migrate --dry預覽并復核全部 diff全局搜索httpAgent、fileFromPath、cloudflare/shims、cloudflare/src無殘留檢查所有.asResponse()/.withResponse()與APIError.headers的用法刪除手動encodeURIComponent的路徑參數tsconfig.json與types包已按運行環境更新全量測試通過測試基線要求 Jest 28測試用例分布在 tests/ 目錄七、常見疑問 FAQQ升級會破壞現有業務嗎官方按 SemVer 發布本次為大版本升級破壞性變更已全部收錄在 MIGRATION.md配合migrate工具可自動化處理絕大多數改動。Qnode-fetch的 polyfill 還要保留嗎不需要。新版直接使用內置 fetch相關 shim 導入cloudflare/shims/*已移除可一并清理。Q上傳文件怎么寫支持File、fetch Response、fs.ReadStream或官方toFile輔助函數Uploadable與toFile仍從cloudflare/core/uploads導出示例見 README.md 的File uploads章節。寫在最后 cloudflare-typescript 新版遷移的核心就是四件事升級包 → 跑migrate命令 → 按第六節清單排查 6 類變更 → 按運行環境配置類型。完成之后你將獲得一個零依賴、跨運行環境、響應類型完全標準化的現代 SDK。更多 API 細節可查閱 api.md 與 CHANGELOG.md核心請求邏輯可參考 src/core/ 目錄源碼。【免費下載鏈接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API項目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 從 node-fetch 到 Web Fetch：cloudflare-typescript 新版本平滑遷移完整指南
從 node-fetch 到 Web Fetchcloudflare-typescript 新版本平滑遷移完整指南【免費下載鏈接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API項目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript如果你正在使用cloudflare-typescriptCloudflare 官方 TypeScript SDK調用 Cloudflare API那么從node-fetch切換到內置Web Fetch的新版本升級就是繞不開的一步。本文是一份面向新手的遷移指南零依賴、自帶一鍵遷移命令按步驟走即可完成平滑升級。一、為什么這次升級值得動手新版 SDK 最大的變化是徹底移除了node-fetch依賴改為使用運行環境內置的 WebfetchAPI實現了零運行時依賴可在 package.json 中看到dependencies為空對象。這帶來了三個直接好處變化點舊版本新版本依賴數量依賴 node-fetch零依賴運行環境主要面向 Node.jsNode 20、Deno、Bun、Cloudflare Workers、瀏覽器通用響應類型Node 專有 Stream/Headers標準 WebReadableStream、Headers遷移工具無官方migrate命令一鍵改代碼二、升級前準備最低環境要求動手前先確認你的工具鏈滿足最低版本要求詳見 MIGRATION.md工具最低版本Node.js20 LTSTypeScript4.9Jest28升級包本身很簡單npm install cloudflare 建議先在功能分支上操作配合 Git 提交方便隨時對比migrate工具的改動。三、最快上手步驟官方 migrate 一鍵遷移命令官方提供了遷移 CLI會自動掃描并改寫你的代碼。推薦先預覽、再應用的兩步走# 第 1 步只預覽改動不寫盤安全試跑 ./node_modules/.bin/cloudflare migrate ./your/src/folders --dry # 第 2 步確認無誤后正式應用 ./node_modules/.bin/cloudflare migrate ./your/src/folders絕大多數項目跑完這兩步就能完成 80% 的遷移工作。剩下的少數場景交給下面的破壞性變更清單逐項排查。四、必須知道的 6 個破壞性變更附前后對比1.asResponse/withResponse返回標準 Web 類型如果你曾對響應做流式處理body現在不再是 Node 的Readable而是 WebReadableStreamAPIError.headers也變成了 WebHeaders實例// 遷移后寫法 import { Readable } from node:stream; const res await client.example.retrieve(string/with/slash).asResponse(); Readable.fromWeb(res.body).pipe(process.stdout);2. 多路徑參數改為命名參數為避免把多個 ID 傳錯順序除最后一個外均需以對象形式命名傳入// Before client.parents.children.retrieve(p_123, c_456); // After client.parents.children.retrieve(c_456, { parent_id: p_123 });完整受影響方法列表收錄在 MIGRATION.md 的折疊章節中排查時可對照查閱。3. 路徑參數默認自動編碼SDK 現在會自動對路徑參數做 URI 編碼請刪掉手寫的encodeURIComponent- client.example.retrieve(encodeURIComponent(string/with/slash)) client.example.retrieve(string/with/slash)4. 請求體必須傳對象端點若接收數組等非對象請求體需要包一層屬性傳入// Before client.example.create([{ name: name }, { name: name }]); // After client.example.create({ items: [{ name: name }, { name: name }] });5.httpAgent移除改用fetchOptions內置 fetch 不支持node:http的 Agent代理配置改為平臺相關的fetchOptionsimport * as undici from undici; const client new Cloudflare({ fetchOptions: { dispatcher: new undici.ProxyAgent(process.env.PROXY_URL), }, });Bun、Deno 的代理寫法略有不同參考 README.md 中Configuring proxies一節的示例即可。6. 導入路徑與內部 API 調整舊寫法新寫法import cloudflare/errorimport cloudflare/core/errorpagination、resource、uploads同理import { APIClient } from cloudflare/coreimport { BaseCloudflare } from cloudflare/clientCloudflare.fileFromPath(...)fs.createReadStream(...)Bun 可用Bun.fileimport cloudflare/shims/web已刪除改為正確配置全局類型cloudflare/src/*cloudflare/*?? 特別注意自動分頁的for await ... of語法不受影響手動分頁則簡化為page.nextPageRequestOptions()一個方法替代原先的nextPageParams()/nextPageInfo()。五、TypeScript 報類型錯誤按運行環境配置升級后若出現Request、Response、Headers相關類型報錯通常是全局類型未配置。對照 MIGRATION.md 的TypeScript troubleshooting章節運行環境tsconfig.json關鍵配置需安裝的類型包Node.jstarget: ES2018建議 ES2020types/node 20Cloudflare Workerstypes: [cloudflare/workers-types]cloudflare/workers-typesBuntarget: ES2018types/bun 1.2.0瀏覽器lib: [DOM, DOM.Iterable, ES2018]無六、升級自檢清單 ?遷移完成后用這份清單快速驗收Node.js ≥ 20、TypeScript ≥ 4.9已執行migrate --dry預覽并復核全部 diff全局搜索httpAgent、fileFromPath、cloudflare/shims、cloudflare/src無殘留檢查所有.asResponse()/.withResponse()與APIError.headers的用法刪除手動encodeURIComponent的路徑參數tsconfig.json與types包已按運行環境更新全量測試通過測試基線要求 Jest 28測試用例分布在 tests/ 目錄七、常見疑問 FAQQ升級會破壞現有業務嗎官方按 SemVer 發布本次為大版本升級破壞性變更已全部收錄在 MIGRATION.md配合migrate工具可自動化處理絕大多數改動。Qnode-fetch的 polyfill 還要保留嗎不需要。新版直接使用內置 fetch相關 shim 導入cloudflare/shims/*已移除可一并清理。Q上傳文件怎么寫支持File、fetch Response、fs.ReadStream或官方toFile輔助函數Uploadable與toFile仍從cloudflare/core/uploads導出示例見 README.md 的File uploads章節。寫在最后 cloudflare-typescript 新版遷移的核心就是四件事升級包 → 跑migrate命令 → 按第六節清單排查 6 類變更 → 按運行環境配置類型。完成之后你將獲得一個零依賴、跨運行環境、響應類型完全標準化的現代 SDK。更多 API 細節可查閱 api.md 與 CHANGELOG.md核心請求邏輯可參考 src/core/ 目錄源碼。【免費下載鏈接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API項目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考