从 node-fetch 到 Web Fetch：cloudflare-typescript 新版本平滑迁移完整指南

从 node-fetch 到 Web Fetch：cloudflare-typescript 新版本平滑迁移完整指南

【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript

如果你正在使用cloudflare-typescript（Cloudflare 官方 TypeScript SDK）调用 Cloudflare API，那么从node-fetch切换到内置Web Fetch的新版本升级就是绕不开的一步。本文是一份面向新手的迁移指南：零依赖、自带一键迁移命令，按步骤走即可完成平滑升级。

一、为什么这次升级值得动手？🚀

新版 SDK 最大的变化是彻底移除了node-fetch依赖，改为使用运行环境内置的 WebfetchAPI，实现了零运行时依赖（可在 package.json 中看到dependencies为空对象）。这带来了三个直接好处：

变化点	旧版本	新版本
依赖数量	依赖 node-fetch	零依赖📦
运行环境	主要面向 Node.js	Node 20+、Deno、Bun、Cloudflare Workers、浏览器通用
响应类型	Node 专有 Stream/Headers	标准 WebReadableStream、Headers
迁移工具	无	官方migrate命令一键改代码

二、升级前准备：最低环境要求

动手前先确认你的工具链满足最低版本要求（详见 MIGRATION.md）：

工具	最低版本
Node.js	20 LTS
TypeScript	4.9
Jest	28

升级包本身很简单：

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，而是 WebReadableStream；APIError.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，代理配置改为平台相关的fetchOptions：

import * 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/error'	import 'cloudflare/core/error'（pagination、resource、uploads同理）
import { APIClient } from 'cloudflare/core'	import { BaseCloudflare } from 'cloudflare/client'
Cloudflare.fileFromPath('...')	fs.createReadStream('...')（Bun 可用Bun.file）
import 'cloudflare/shims/web'	已删除，改为正确配置全局类型
cloudflare/src/*	cloudflare/*

⚠️ 特别注意：自动分页的for await ... of语法不受影响；手动分页则简化为page.nextPageRequestOptions()一个方法，替代原先的nextPageParams()/nextPageInfo()。

五、TypeScript 报类型错误？按运行环境配置

升级后若出现Request、Response、Headers相关类型报错，通常是全局类型未配置。对照 MIGRATION.md 的"TypeScript troubleshooting"章节：

运行环境	tsconfig.json关键配置	需安装的类型包
Node.js	"target": "ES2018"（建议 ES2020+）	@types/node >= 20
Cloudflare Workers	"types": ["@cloudflare/workers-types"]	@cloudflare/workers-types
Bun	"target": "ES2018"	@types/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/ 目录）

七、常见疑问 FAQ

Q：升级会破坏现有业务吗？官方按 SemVer 发布，本次为大版本升级，破坏性变更已全部收录在 MIGRATION.md，配合migrate工具可自动化处理绝大多数改动。

Q：node-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