从 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），仅供参考