# https://github.com/cloudflare/cloudflare-typescript 项目说明书

生成时间：2026-06-06 08:00:03 UTC

## 目录

- [项目概览与代码架构](#page-overview)
- [API 资源、请求调用与分页](#page-resources)
- [客户端配置、错误处理与高级用法](#page-config)
- [版本演进、破坏性变更与社区高频问题](#page-versioning)

<a id='page-overview'></a>

## 项目概览与代码架构

### 相关页面

相关主题：[API 资源、请求调用与分页](#page-resources), [客户端配置、错误处理与高级用法](#page-config)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/resources/ai/models/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts)
- [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts)
- [src/resources/ai/models/schema.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/schema.ts)
- [src/resources/zero-trust/dlp/profiles/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/index.ts)
- [src/resources/zero-trust/dlp/profiles/profiles.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/profiles.ts)
- [src/resources/zero-trust/dlp/profiles/custom.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/custom.ts)
- [src/resources/zero-trust/dlp/profiles/predefined.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/predefined.ts)
- [src/resources/zero-trust/dex/commands/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/index.ts)
- [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts)
</details>

# 项目概览与代码架构

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

## 资源树与命名空间分层

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

```mermaid
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](https://github.com/cloudflare/cloudflare-typescript/issues/2553)）。用户在升级时经常遇到的具体痛点包括：

- KV `Key['metadata']` 类型被收紧为 `Record<string, unknown>`，无法表达任意 JSON 字符串（Issue #1238）。
- `pages.projects.list` 在 6.x 中仍返回旧的 `DeploymentsSinglePage` 泛型（Issue #2757）。
- `formdata-node` 间接引入已废弃的 `node-domexception@1.0.0`，需在 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 文档](https://developers.cloudflare.com/api/)
- [Stainless 生成器说明](https://www.stainless.com/)
- 相关 Wiki 页面：`v6 升级与破坏性变更`、`分页与游标使用指南`、`Zero Trust 资源总览`

---

<a id='page-resources'></a>

## API 资源、请求调用与分页

### 相关页面

相关主题：[项目概览与代码架构](#page-overview), [客户端配置、错误处理与高级用法](#page-config)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts)
- [src/resources/ai/models/schema.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/schema.ts)
- [src/resources/ai/models/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts)
- [src/resources/zero-trust/dlp/profiles/profiles.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/profiles.ts)
- [src/resources/zero-trust/dlp/profiles/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/index.ts)
- [src/resources/zero-trust/dlp/profiles/predefined.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/predefined.ts)
- [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts)
- [src/resources/zero-trust/dex/commands/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/index.ts)
</details>

# API 资源、请求调用与分页

## 概述

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

## 资源层级与组织

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](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts)

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

## 请求调用机制

### 基本请求模板

所有 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](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts)

### Schema 查询

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

### Predefined 配置更新

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

## 分页模型

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

```mermaid
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](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts)
- `V4PagePaginationArray<T>`:适用于 v4 API 直接返回数组的分页。`Models.list` 即此类型,响应元素类型是 `unknown`（开放搜索结果）。资料来源：[src/resources/ai/models/models.ts:28-30](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts)
- `SinglePage<T>`:适用于一次性返回的单页结果（如 `ProfilesSinglePage`）。资料来源：[src/resources/zero-trust/dlp/profiles/profiles.ts:1-30](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/profiles.ts)

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

## 常见问题与社区反馈

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

## See Also

- [Workers AI 资源文档](#)（如需展开 `ai.models` / `ai.run` 的端点）
- [Zero Trust DLP Profiles](#)（如需进一步说明 `custom` 与 `predefined` 的字段差异）
- 升级到 v6 的迁移指引（见 [v6.0.0 Release Notes](https://github.com/cloudflare/cloudflare-typescript/releases/tag/v6.0.0)）

---

<a id='page-config'></a>

## 客户端配置、错误处理与高级用法

### 相关页面

相关主题：[项目概览与代码架构](#page-overview), [API 资源、请求调用与分页](#page-resources), [版本演进、破坏性变更与社区高频问题](#page-versioning)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md)
- [src/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/index.ts)
- [src/client.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/client.ts)
- [src/core.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/core.ts)
- [src/error.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/error.ts)
- [src/pagination.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/pagination.ts)
- [src/shims/node.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/shims/node.ts)
- [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts)
</details>

# 客户端配置、错误处理与高级用法

## 概述

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

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

---

## 客户端配置

### 初始化与认证

`Cloudflare` 类位于 SDK 入口文件，是所有资源访问的根。在 [src/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/index.ts) 中导出的 `Cloudflare` 同时支持 API Token 与传统 API Key + Email 的双认证模式 [资料来源：[src/index.ts]()]。最小化配置示例：

```ts
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN!,
});
```

### 基础 URL 与超时

客户端构造函数接受 `baseURL`、`timeout`、`maxRetries`、`httpAgent` 等选项，对应到内部 `Core.RequestOptions` 类型 [资料来源：[src/core.ts]()]。该类型由分页与重试中间件统一消费，因此调整这些字段会影响**所有**资源方法而无需逐个设置。

### 环境变量约定

虽然 SDK 未在源码中硬性要求环境变量名，但社区习惯使用：

| 选项 | 推荐环境变量 | 说明 |
| --- | --- | --- |
| `apiToken` | `CLOUDFLARE_API_TOKEN` | 推荐方式，权限可收敛到单资源 |
| `apiKey` + `email` | `CLOUDFLARE_API_KEY` / `CLOUDFLARE_EMAIL` | 旧式全局密钥，v5 起被标记为迁移目标 |
| `baseURL` | `CLOUDFLARE_API_BASE_URL` | 私有部署或测试桩场景 |

---

## 错误处理

### 错误类层次

SDK 在 [src/error.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/error.ts) 中定义了一套与 HTTP 语义对应的错误类型，包括 `CloudflareError`、`APIError`、`APIConnectionError`、`APIConnectionTimeoutError` 与 `APIUserAbortError` [资料来源：[src/error.ts]()]。`APIError` 进一步暴露 `status`、`headers`、`error`（含 `code` 字段）以及 `requestID`，便于与 Cloudflare 控制台日志交叉定位。

### 典型处理模式

```ts
import Cloudflare, { APIError } from 'cloudflare';

try {
  await client.accounts.zones.list({ account_id: '...' });
} catch (err) {
  if (err instanceof APIError && err.status === 429) {
    // 命中速率限制
  } else {
    throw err;
  }
}
```

### 与社区痛点的关联

Issue [#1176](https://github.com/cloudflare/cloudflare-typescript/issues/1176) 报告"稳定性、破坏性变更与可靠性"问题，核心症结之一就是错误信息不够结构化导致难以在 CI 中识别。升级到 v6 后，错误对象进一步统一为 `Result` 风格（`{ success, errors, messages, result_info }`），便于直接基于 `success` 字段做短路控制 [资料来源：[src/error.ts]()]。

---

## 高级用法

### 分页模型

SDK 在 [src/pagination.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/pagination.ts) 中实现了四种分页策略：`SinglePage`、`PagePagination`、`V4PagePagination` 与 `CursorPagination`，并通过 `Core.PagePromise` 暴露 `for await ... of` 风格的异步迭代。例如 `client.zeroTrust.dex.commands.devices.list(...)` 返回的就是 `PagePromise<DeviceListResponsesV4PagePagination, DeviceListResponse>` [资料来源：[src/resources/zero-trust/dex/commands/devices.ts]()]：

```ts
for await (const page of client.zeroTrust.dex.commands.devices.list(
  { account_id: '...', page: 1, per_page: 25 },
)) {
  for (const device of page.devices ?? []) {
    console.log(device.id);
  }
}
```

### 请求流程总览

```mermaid
flowchart LR
  A[业务代码] --> B[Cloudflare 客户端]
  B --> C{中间件管线}
  C -->|鉴权头注入| D[baseURL 解析]
  D --> E[分页与重试]
  E -->|原生 fetch| F[Cloudflare API]
  F --> G{HTTP 状态}
  G -->|2xx| H[PagePromise 迭代]
  G -->|4xx/5xx| I[APIError 抛出]
  I --> J[业务 try/catch]
  H --> J
```

### 重试、超时与中止

`maxRetries` 默认 2 次，对幂等请求自动重试；可针对单次调用通过 `options: { maxRetries: 0 }` 覆盖。`AbortSignal` 可透传至 `Core.RequestOptions`，用于在长轮询（如 `client.zeroTrust.dex.commands` 的远程捕获场景）中主动取消 [资料来源：[src/core.ts]()]。

### Node.js 运行环境

自 v6.0.0 起，SDK 移除对 `node-fetch` 的依赖，统一使用 Node 18+ 内置的 `fetch` 与 `FormData`，相关 shim 由 [src/shims/node.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/shims/node.ts) 提供。社区 Issue [#2553](https://github.com/cloudflare/cloudflare-typescript/issues/2553) 跟踪了这一升级，它同时消除了 [#2267](https://github.com/cloudflare/cloudflare-typescript/issues/2267) 中的 `punycode` 警告 [资料来源：[src/shims/node.ts]()]。在 Cloudflare Workers、Browser、Node 与 Deno 等多运行时上，使用体验保持一致。

### 避免常见误用

- **不要**直接 `JSON.parse(await res.text())`——会绕过 SDK 的 `Result` 包装，可能丢失 `requestID` 等诊断信息。
- **不要**在 `for await` 循环内部对 `page` 做缓存——分页对象通常只在迭代时有效。
- **不要**忽略 `APIError.status === 404` 与 `success === false` 的差异——前者来自传输层，后者来自 API 业务层。

---

## See Also

- [资源概览与子资源索引](README.md)
- [v6.0.0 重大版本变更说明](https://github.com/cloudflare/cloudflare-typescript/releases/tag/v6.0.0)
- [Cloudflare REST API 官方文档](https://developers.cloudflare.com/api/)

---

<a id='page-versioning'></a>

## 版本演进、破坏性变更与社区高频问题

### 相关页面

相关主题：[项目概览与代码架构](#page-overview), [客户端配置、错误处理与高级用法](#page-config)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [CHANGELOG.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/CHANGELOG.md)
- [package.json](https://github.com/cloudflare/cloudflare-typescript/blob/main/package.json)
- [.release-please-manifest.json](https://github.com/cloudflare/cloudflare-typescript/blob/main/.release-please-manifest.json)
- [release-please-config.json](https://github.com/cloudflare/cloudflare-typescript/blob/main/release-please-config.json)
- [src/resources/ai/models/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts)
- [src/resources/zero-trust/dlp/profiles/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/index.ts)
- [src/resources/zero-trust/dlp/profiles/profiles.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/profiles.ts)
- [src/resources/zero-trust/dlp/profiles/custom.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/custom.ts)
- [src/resources/zero-trust/dex/commands/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/index.ts)
- [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts)
</details>

# 版本演进、破坏性变更与社区高频问题

本页面向需要升级 SDK、规划长期依赖或在生产环境中排查回归问题的开发者，梳理 `cloudflare-typescript` 的发布节奏、破坏性变更的来源以及社区中反馈最集中的几类问题。

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

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

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

| 版本 | 性质 | 关键变化 |
| --- | --- | --- |
| v5.0.0 | 重大版本 | 资源面与生成器大幅调整，事后补发了详细变更说明 |
| v5.1.0 / v5.2.0 | 次要版本 | 新增负载均衡监控组、Radar AS-SET 查询等端点 |
| v6.0.0-beta.1 / beta.2 | 预发布 | 大规模重构，逐步替换 v5.x 的生成面 |
| v6.0.0 | 重大版本 | 新增 11 个顶层资源，50+ 资源扩展子资源，API 资源总数从约 96 增长 |
| v6.1.0 / v6.2.0 / v6.3.0 | 周更小版本 | 持续追加 DLS、Advanced TCP Protection、Security Center Insights 等资源 |

资料来源：[CHANGELOG.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/CHANGELOG.md)、[package.json](https://github.com/cloudflare/cloudflare-typescript/blob/main/package.json)

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

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

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

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

3. **字段级弃用与联合类型重塑**。在 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](https://github.com/cloudflare/cloudflare-typescript/blob/main/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](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/predefined.ts)

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

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

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

| 问题 | 议题 | 根因 | 建议策略 |
| --- | --- | --- | --- |
| Node 21+ 出现 `Punycode` 弃用警告 | [#2267](https://github.com/cloudflare/cloudflare-typescript/issues/2267) | `node-fetch` 间接依赖 `punycode` | 跟踪 v6.x 移除 `node-fetch` 的进展；过渡期可设置 `NODE_OPTIONS=--no-deprecation` 抑制告警 |
| `node-domexception@1.0.0` 废弃 | [#2660](https://github.com/cloudflare/cloudflare-typescript/issues/2660) | `formdata-node` 传递依赖 | 升级到 v6.x 后可同步清除；如仍锁旧版，使用 `overrides`/`resolutions` 显式钉版本 |
| 分页返回类型错误（如 `pages.projects.list`） | [#2757](https://github.com/cloudflare/cloudflare-typescript/issues/2757) | 生成器对 `SinglePage` 的判定偏差 | 升级前用 `git log` 确认是否已修复；运行时仍可用 `for await` 解包，规避类型检查 |
| KV `Key['metadata']` 类型过窄 | [#1238](https://github.com/cloudflare/cloudflare-typescript/issues/1238) | 由 `unknown` 收紧为 `Record<string, unknown>` | 调用方手动断言 `as unknown` 或封装适配层；订阅该议题的更新 |
| 难以理解 v5.0.0 到底改了什么 | [#2673](https://github.com/cloudflare/cloudflare-typescript/issues/2673) | 初次变更说明不充分 | 依赖后续补发的 [retroactive changelog](https://github.com/cloudflare/cloudflare-typescript/releases/tag/v5.0.0) 与 `git diff v4.5.0...v5.0.0` |
| RealtimeKit “Add Participant” 缺失 | [#2737](https://github.com/cloudflare/cloudflare-typescript/issues/2737) | 资源未及时收录 | 在 release 日历确认是否进入周更批次，必要时提交 PR 附 OpenAPI 规范片段 |

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

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

```mermaid
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](https://github.com/cloudflare/cloudflare-typescript/blob/main/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](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/profiles.ts)

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

## See Also

- [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/CONTRIBUTING.md)
- [Releases](https://github.com/cloudflare/cloudflare-typescript/releases)
- 社区跟踪：[Release Calendar](https://github.com/cloudflare/cloudflare-typescript/issues/2755)、[Major version upgrade](https://github.com/cloudflare/cloudflare-typescript/issues/2553)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: cloudflare/cloudflare-typescript; human_manual_source: deepwiki_human_wiki -->