内网也能调 Cloudflare API：cloudflare-typescript 代理配置与自定义 fetch 技巧清单

内网也能调 Cloudflare APIcloudflare-typescript 代理配置与自定义 fetch 技巧清单【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript项目简介Cloudflare 官方 TypeScript SDKcloudflare-typescript是 Cloudflare 官方出品的 TypeScript/JavaScript SDKnpm 包名cloudflare让你用类型安全的方式调用 Cloudflare REST API——从 Zones、DNS、Workers 到 AI、KV、R2 等上百个资源全部内置自动分页、重试、超时和完整的请求/响应类型定义。如果你的运行环境在内网、无法直连api.cloudflare.com或者想用自己的网络层代理、Mock、埋点这篇文章给你一份可落地的代理配置与自定义 fetch 技巧清单。一键安装# 直接安装 SDK npm install cloudflare # 如需查看/修改源码可克隆仓库 git clone https://gitcode.com/gh_mirrors/cl/cloudflare-typescript拿到客户端只需两行核心逻辑见src/client.tsimport Cloudflare from cloudflare; const client new Cloudflare({ apiToken: process.env[CLOUDFLARE_API_TOKEN], // 默认读取该环境变量可省略 });技巧 1用 baseURL 把请求指到你的代理网关客户端构造函数支持baseURL选项默认值是https://api.cloudflare.com/client/v4见 src/client.ts 中ClientOptions.baseURL的定义。把它改成公司网关或本地 Mock 地址即可让所有请求走内网const client new Cloudflare({ apiToken: process.env[CLOUDFLARE_API_TOKEN], baseURL: http://gateway.intranet.com/cf-proxy/client/v4, });也可以不改代码直接用环境变量CLOUDFLARE_BASE_URL覆盖多环境切换非常方便。技巧 2三种运行时的代理配置方法官方推荐的做法是通过fetchOptions注入运行时的代理选项README 中 “Configuring proxies” 一节。不同运行时写法不同运行时关键做法要点Node.js用 undici 的ProxyAgent通过fetchOptions.dispatcher传入最常用支持 HTTP/HTTPS 代理Bun直接传fetchOptions.proxy字符串一个字段搞定DenoDeno.createHttpClient({ proxy })后放入fetchOptions.client需先创建 HTTP 客户端Node 示例内网代理场景最常用import * as undici from undici; const proxyAgent new undici.ProxyAgent(http://proxy.intranet:8888); const client new Cloudflare({ apiToken: process.env[CLOUDFLARE_API_TOKEN], fetchOptions: { dispatcher: proxyAgent, }, }); 小技巧fetchOptions是全局默认值单次请求还可以传独立的fetchOptions覆盖它方便对个别慢接口单独加参数。技巧 3自定义 fetch 的三种姿势SDK 默认使用全局fetch见src/internal/shims.ts的getDefaultFetch。想完全接管网络层有三种方式整体替换全局 fetchglobalThis.fetch myFetch适合老项目统一改造。构造时注入推荐import myFetch from my-fetch; const client new Cloudflare({ apiToken: process.env[CLOUDFLARE_API_TOKEN], fetch: myFetch, // 自定义 fetch 函数 });派生新客户端用client.withOptions({ fetch: myFetch })在不动原客户端的情况下换网络层一个项目里可以并存“直连”和“走代理”两个客户端实例。自定义 fetch 里还能顺手做请求埋点、Mock 测试、日志留痕——官方测试就是用注入的fetch来断言发出的 URL 和请求体参考tests/index.test.ts中的custom fetch用例。技巧 4内网弱网下的超时与重试调优内网链路长、不稳定两个参数直接调timeout单请求超时默认 1 分钟超时抛APIConnectionTimeoutErrormaxRetries默认自动重试 2 次指数退避对 408、409、429、5xx 和网络断连都生效。const client new Cloudflare({ apiToken: process.env[CLOUDFLARE_API_TOKEN], timeout: 20 * 1000, // 20 秒 maxRetries: 5, // 内网多给几次机会 });重试逻辑含Retry-After头解析位于src/client.ts的retryRequest方法行为透明可控。技巧 5开 debug 日志排查代理是否生效内网排障最快的方式是把日志开到debug能看到每个请求的 URL、响应状态与耗时const client new Cloudflare({ logLevel: debug, // 或设环境变量 CLOUDFLARE_LOGdebug });日志格式与工具在src/internal/utils/log.ts还可传入 pino、winston 等第三方 logger 接管输出。环境变量速查清单环境变量作用CLOUDFLARE_API_TOKENAPI Token 认证推荐CLOUDFLARE_API_KEY/CLOUDFLARE_EMAIL旧版 Global Key 认证CLOUDFLARE_BASE_URL覆盖默认 API 地址指向代理网关CLOUDFLARE_LOG日志级别debug/info/warn/error/offCLOUDFLARE_CUSTOM_HEADERS按行注入自定义请求头如X-Proxy-Tag: internal总结想让所有请求走内网代理优先baseURL指向网关或按运行时用fetchOptions配代理Node 用 undiciProxyAgent想接管网络层埋点/Mock/测试构造时传fetch或用withOptions派生客户端弱网环境记得调大timeout和maxRetries并用logLevel: debug快速定位问题。掌握这份清单无论在公司内网还是边缘环境cloudflare-typescript 都能稳定连上 Cloudflare API。【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考