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