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