cloudflare-typescript 是 Cloudflare 官方维护的 TypeScript SDK，用于以强类型方式访问 Cloudflare 的 REST API。仓库中的全部源码文件顶部都带有 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. 注释，表明代码由 Stainless 从 OpenAPI 规范自动生成，不应手工编辑（例如 src/resources/ai/models/index.ts）。社区中关于稳定性与破坏性变更的讨论（如 Issue #1176、#2673）也反复强调该 SDK 的演进与上游 OpenAPI 描述保持一致。

资源树与命名空间分层

SDK 将每一个 Cloudflare API 端点映射为一个 APIResource 子类，并按 URL 路径逐层挂载到根 Client 实例上，形成可深度遍历的"资源树"。下面是 client.ai.models 与 client.zeroTrust.dlp.profiles 两条典型路径的对照：

graph TD
  Client[Client]
  Client --> AI[ai]
  Client --> ZT[zeroTrust]
  AI --> Models[models]
  Models --> Schema[schema]
  ZT --> DLP[dlp]
  DLP --> Profiles[profiles]
  Profiles --> Custom[custom]
  Profiles --> Predefined[predefined]
  ZT --> DEX[dex]
  DEX --> Commands[commands]
  Commands --> Devices[devices]
  Commands --> Downloads[downloads]
  Commands --> Quota[quota]

每层目录对应一个 index.ts 桶文件，仅做 export 聚合，不再包含运行时逻辑。src/resources/ai/models/index.ts 同时再导出命名空间类型 ModelListResponsesV4PagePaginationArray、Models 以及若干 *Params/*Response 类型别名；src/resources/zero-trust/dlp/profiles/index.ts 则把 Custom、Predefined、Profiles 三个子资源以及它们各自的参数与响应类型从同级文件再次聚合并 re-export，从而为使用者提供统一的入口面。

APIResource 类与子资源挂载

每个具体资源都继承自 APIResource，并在构造函数中接收父级 _client，再在自身字段上实例化下一级资源，从而实现"懒加载 + 链式挂载"。例如 Models 类在内部新建 SchemaAPI.Schema 并以 schema 字段暴露（资料来源：src/resources/ai/models/models.ts:13-15）；Profiles 类则把 Custom 与 Predefined 两个子类以 custom / predefined 字段形式暴露给上层（资料来源：src/resources/zero-trust/dlp/profiles/profiles.ts:0-0）。这种模式同样出现在 Commands 中——src/resources/zero-trust/dex/commands/index.ts 把 Commands、Devices、Downloads、Quota 一并 re-export，调用方只需 client.zeroTrust.dex.commands.devices.list(...) 即可命中 /accounts/{account_id}/dex/commands/devices 路径。

请求、响应与分页抽象

所有方法最终都委托到 Core.APIPromise 或 Core.PagePromise，并在返回值上保留分页游标能力。get 类方法（例如 Schema.get）使用 _thenUnwrap((obj) => obj.result) 把 Cloudflare API 通用信封 { result, success, errors, messages } 拆出真正的载荷（资料来源：src/resources/ai/models/schema.ts:11-19）。列表类方法则使用 V4PagePagination / V4PagePaginationArray 两种游标类来描述响应形态：devices.list 使用 V4PagePagination（资料来源：src/resources/zero-trust/dex/commands/devices.ts:35-37），而 models.list 使用 V4PagePaginationArray，并通过 getAPIList 在内部把 account_id 路径参数与剩余查询参数分离后注入模板路径（资料来源：src/resources/ai/models/models.ts:21-28）。

类型命名空间与判别联合

针对"自定义 / 预定义 / 集成"等存在多种形态的 DLP Profile，代码采用了 Profile = CustomProfile | PredefinedProfile | IntegrationProfile 形式的判别联合，并在 namespace Profile { ... } 下分别声明各形态字段（资料来源：src/resources/zero-trust/dlp/profiles/profiles.ts:0-0）。子级条目（CustomEntry、WordListEntry、DocumentFingerprintEntry 等）同样通过 type: 'custom' | 'word_list' | 'document_fingerprint' 字符串字面量做判别，并配合 CustomAPI.Pattern 这种二级命名空间携带模式细节。已废弃字段（如 enabled、profile_id）保留但标 @deprecated，在 IDE 静态检查中会触发删除线提示。Custom / Predefined 子资源文件复用相同 CustomProfile 命名空间，使两套端点对调用方共享一致的类型签名（资料来源：src/resources/zero-trust/dlp/profiles/custom.ts:0-0 与 src/resources/zero-trust/dlp/profiles/predefined.ts:0-0）。

版本节奏与社区关注点

当前最新稳定版为 v6.3.0（发布日期 2026-05-21），仓库已转向周更节奏，v6.2.0、v6.3.0 等版本以每周三/四的频率推进（社区证据：Release Calendar issue #2755）。v6.0.0 引入了 11 个新的顶层资源、50+ 资源的新方法，以及 node-fetch → 原生 fetch 的迁移所伴随的破坏性变更（社区证据：Upcoming major version upgrade #2553）。用户在升级时经常遇到的具体痛点包括：

• KV Key['metadata'] 类型被收紧为 Record<string, unknown>，无法表达任意 JSON 字符串（Issue #1238）。
• pages.projects.list 在 6.x 中仍返回旧的 DeploymentsSinglePage 泛型（Issue #2757）。
• formdata-node 间接引入已废弃的 [email protected]，需在 lockfile 中显式覆盖（Issue #2660）。

选型与使用建议

对希望基于 cloudflare-typescript 二次封装或在 Cloudflare Workers 内调用的开发者，建议遵循以下实践：① 通过顶层 index.ts 桶文件确认资源挂载路径，避免直接 import 深层文件路径，因为 Stainless 重生成可能改变目录；② 凡涉及列表的接口，优先使用 for await 模式消费 PagePromise，与 SDK 自带的 V4PagePagination 行为保持一致；③ 对 DLP 这类含判别联合的资源，编写 switch/case 时务必覆盖 type 字符串字面量，否则 TypeScript 的收窄分析会失效。

See Also

• Cloudflare API 文档
• Stainless 生成器说明
• 相关 Wiki 页面：v6 升级与破坏性变更、分页与游标使用指南、Zero Trust 资源总览

概述

cloudflare-typescript 是 Cloudflare API 的官方 TypeScript SDK,采用"资源（Resource）—方法（Method）"的面向对象结构组织所有 Cloudflare API 端点。代码中每个端点都被生成为一个继承自 APIResource 的类,实例方法对应一次 HTTP 请求,而分页列表端点则返回 PagePromise 以支持自动翻页。资料来源：src/resources/ai/models/models.ts:1-10、src/resources/zero-trust/dlp/profiles/profiles.ts:1-30

资源层级与组织

SDK 中的资源按 Cloudflare 官方分类组织成多层目录,每个目录都通过 index.ts 汇总导出。例如 ai/models 目录聚合了 Models 和 Schema 两个子资源,使用方既可写 client.ai.models.list(...),也可以通过 client.ai.models.schema.get(...) 访问嵌套资源。资料来源：src/resources/ai/models/index.ts:1-8

同理,Zero Trust DLP 的"profiles"资源进一步拆分为 custom 与 predefined 两条子路径,二者均通过 zeroTrust.dlp.profiles.<sub> 访问,并在 predefined.ts 中以 PredefinedUpdateParams 等类型明确入参。资料来源：src/resources/zero-trust/dlp/profiles/index.ts:1-19、src/resources/zero-trust/dlp/profiles/predefined.ts:1-30

请求调用机制

基本请求模板

所有 API 方法的签名遵循统一模板:从 params 中解构出 account_id 等路径参数放入 URL 路径,其余字段作为 query 或 body 提交。例如 Models.list 将 account_id 拼接到 /accounts/${account_id}/ai/models/search 路径上,其余字段透传为 query。资料来源：src/resources/ai/models/models.ts:14-25

Schema 查询

Schema.get 是一个非分页的简单 GET 端点,接受 account_id（路径参数）和 model（查询参数）,返回 Workers AI 模型的输入输出 JSON Schema 定义。响应会通过 _thenUnwrap 自动解包 obj.result,只把核心数据交给调用方。资料来源：src/resources/ai/models/schema.ts:8-22

Predefined 配置更新

Predefined.update 使用 PUT 方法,路径为 /accounts/${account_id}/dlp/profiles/predefined/${profileId}/config,请求体由解构后的 body 提供。该方法为 Terraform 集成做了特殊设计,只允许启用或禁用条目。资料来源：src/resources/zero-trust/dlp/profiles/predefined.ts:1-30

分页模型

SDK 提供了多种分页类以适配 Cloudflare 后端的不同协议:

flowchart LR
    A[APIResource 列表方法] --> B{返回类型}
    B -->|V4PagePagination| C[PagePromise + AsyncIterator]
    B -->|V4PagePaginationArray| D[PagePromise + AsyncIterator]
    B -->|SinglePage| E[PagePromise + AsyncIterator]
    C --> F[for await 自动翻页]
    D --> F
    E --> F

• V4PagePagination<T>:适用于 v4 API 的标准对象式分页响应。Devices.list 即采用该类,返回最近 1 小时内支持 WARP 远程捕获的设备列表。资料来源：src/resources/zero-trust/dex/commands/devices.ts:18-32
• V4PagePaginationArray<T>:适用于 v4 API 直接返回数组的分页。Models.list 即此类型,响应元素类型是 unknown（开放搜索结果）。资料来源：src/resources/ai/models/models.ts:28-30
• SinglePage<T>:适用于一次性返回的单页结果（如 ProfilesSinglePage）。资料来源：src/resources/zero-trust/dlp/profiles/profiles.ts:1-30

所有分页方法均通过 getAPIList 工厂构造,并返回 Core.PagePromise,可直接配合 for await ... of 自动逐页迭代。

常见问题与社区反馈

• 分页返回类型错误:社区报告 client.pages.projects.list 等部分方法返回的 PagePromise 泛型参数不正确,使用方需关注类型推断。资料来源：issues/2757
• 稳定性与破坏性变更:多个版本（v5、v6）在资源结构与请求类型上做过大幅调整,建议升级时仔细比对 v5→v6 的迁移说明。资料来源：issues/1176、issues/2673
• 新资源频繁增加:v6.x 系列几乎每周发布,新增 DLS、Security Center Insights 等资源并扩展已有资源的方法,跟踪 getAPIList 调用方需要随时关注方法签名变化。资料来源：v6.1.0 Release、v6.3.0 Release

See Also

• Workers AI 资源文档（如需展开 ai.models / ai.run 的端点）
• Zero Trust DLP Profiles（如需进一步说明 custom 与 predefined 的字段差异）
• 升级到 v6 的迁移指引（见 v6.0.0 Release Notes）

概述

cloudflare-typescript 是 Cloudflare 官方维护的 TypeScript SDK，提供与 Cloudflare REST API v4 完全对齐的类型化客户端。本页聚焦于 SDK 使用过程中跨所有资源均需了解的三类主题：客户端初始化与配置、错误处理模型、以及分页 / 重试 / 运行环境等高级用法。

社区反馈显示，用户最关心的并非单个资源的方法签名，而是与运行环境、依赖兼容性相关的"基础设施"问题。例如 Issue #2267 反映了 node-fetch / punycode 在 Node 21+ 中的弃用警告，Issue #2660 指出 formdata-node 的传递性弃用，这两项均在 v6.0.0 重大版本升级中得到解决 资料来源：[README.md]。

一、版本发布节奏与版本族谱

cloudflare-typescript 由 Stainless 从 OpenAPI 规范自动生成，因此其版本号与上游 API 的演进紧密耦合。根据社区维护的 Release Calendar，从 v6.2.0 起 SDK 切换为每周发版节奏，目标日固定在周三或周四（例如 v6.2.0 = 2026-05-13/14，v6.3.0 = 2026-05-20/21），以便快速同步 Cloudflare 后端 API 资源的扩张。

按时间线梳理，主要版本族谱如下：

资料来源：CHANGELOG.md、package.json

二、破坏性变更的来源与迁移路径

SDK 的破坏性变更主要有三类来源，每一类都会直接影响调用方代码：

1. 底层依赖替换。node-fetch 在 Node 21+ 上触发 Punycode 弃用警告（社区议题 #2267），同时 formdata-node 引入的 [email protected] 也已弃用（议题 #2660）。在 #2553 中，Cloudflare 团队明确表示将以主版本升级方式移除 node-fetch，迁移到 Node 18+ 自带的原生 fetch，从而一次性解决以上两个废弃依赖问题。

1. 类型收敛与重命名。v3.x → v5.x 之间曾出现 pages.projects.list 返回类型长期不正确的回归（议题 #2757）；而 KV 的 Key['metadata'] 在 3.2.0 → 3.3.0 之间被收紧为 Record<string, unknown>，相比原本可承载任意 JSON 字符串的 unknown 偏窄（议题 #1238）。两者都提示用户：在升级后应当对使用分页或 metadata 字段的代码进行类型再校验。

1. 字段级弃用与联合类型重塑。在 DLP Profiles 资源中，类型层已经埋下弃用标记，例如 CustomEntry.enabled、CustomEntry.profile_id 等字段被标注为 @deprecated：

``ts export interface CustomEntry { id: string; /** @deprecated */ enabled: boolean; // ... /** @deprecated */ profile_id?: string | null; } ``

资料来源：src/resources/zero-trust/dlp/profiles/custom.ts

同时 PredefinedEntry.variant 被建模为 UnionMember0 | UnionMember1 的判别联合，方便未来在 PromptTopic 与 General 之外扩展新的预定义类型：

``ts variant?: PredefinedEntry.UnionMember0 | PredefinedEntry.UnionMember1; ``

资料来源：src/resources/zero-trust/dlp/profiles/predefined.ts

迁移实践上，社区普遍建议：

• 跨主版本升级时，先在分支中固定旧版本与新版本并行跑回归测试，重点关注分页响应（PagePromise<...>）与 metadata、pattern 等“宽类型”字段。
• 关注 v6.0.0 中“11 个新顶层资源 + 50+ 子资源”的影响面，因为很多调用入口从单层 client.xxx 变成了 client.xxx.yyy 的二级路径。
• 当遇到“changelog 不可读”的反馈（参见议题 #2673）时，优先以 git diff v5.x..v6.x 对比生成的资源文件，并结合 release notes 中的 commit 链接定位。

三、社区高频问题与对应策略

四、SDK 内部演进模式：从单资源到子资源树

观察最新一批资源文件，可以归纳出 SDK 在 v6 阶段的两类典型演进路径：

graph TD
  A[Top-level Resource] --> B[Sub-resource: list/get/create/update/delete]
  A --> C[Sub-resource: specialized endpoint]
  A --> D[Helper: Quota / Downloads]
  B --> E[V4PagePagination response]
  C --> F[V4PagePagination response]
  D --> G[Single-shot response]

• 聚合型扩展：zeroTrust.dex.commands 在 v6 中并入了 devices、downloads、quota 等子资源，所有列表接口统一返回 Core.PagePromise<...,V4PagePagination>，便于通过 for await 自动翻页。

``ts return this._client.getAPIList( /accounts/${account_id}/dex/commands/devices, DeviceListResponsesV4PagePagination, { query, ...options }, ); ``

资料来源：src/resources/zero-trust/dex/commands/devices.ts

• 类型分支加固：DLP Profiles 资源在 v6 期间逐步将 PredefinedEntry.variant、IntegrationProfile.shared_entries 等字段改写为判别联合，使 Custom | Predefined | Integration 三类 profile 在类型层即可被精确区分，减少运行时的 as 断言。资料来源：src/resources/zero-trust/dlp/profiles/profiles.ts

这种“自顶向下分桶 + 自底向上用判别联合收紧”的模式，意味着当社区提出新功能请求（例如 RealtimeKit 的 Add Participant）时，多数情况下并不需要修改既有调用入口，而是在对应资源的命名空间下追加新的子资源文件，迁移成本可控。

See Also

• README.md
• CONTRIBUTING.md
• Releases
• 社区跟踪：Release Calendar、Major version upgrade

Pitfall Log / 踩坑日志

项目：cloudflare/cloudflare-typescript

摘要：发现 12 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：The return type of pages.projects.list is still wrong。

1. 安装坑 · 来源证据：The return type of `pages.projects.list` is still wrong

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：The return type of pages.projects.list is still wrong
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fd79754a428c425783f16ba5439e69bf | https://github.com/cloudflare/cloudflare-typescript/issues/2757 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Upcoming major version upgrade

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Upcoming major version upgrade
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e1faaf55476548078001738e87c00975 | https://github.com/cloudflare/cloudflare-typescript/issues/2553 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 维护坑 · 来源证据：Release Calendar

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release Calendar
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2ac3a8bda7d84bf4addc54959229466b | https://github.com/cloudflare/cloudflare-typescript/issues/2755 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安全/权限坑 · 来源证据：RealtimeKit Add Participant API

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RealtimeKit Add Participant API
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_988272604e4b47dfa6ac077e17e870c7 | https://github.com/cloudflare/cloudflare-typescript/issues/2737 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

5. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 cloudflare-typescript 与安装入口 cloudflare 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npm install cloudflare
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | repo=cloudflare-typescript; install=cloudflare

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | README/documentation is current enough for a first validation pass.

7. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 建议检查：确认是否有离线 demo、mock 数据或可替代服务。
• 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。
• 证据：packet_text.keyword_scan | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | matched external service / cloud / webhook / database keyword

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | last_activity_observed missing

9. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | no_demo; severity=medium

10. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | no_demo; severity=medium

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare | release_recency=unknown