Cloudflare API 入门：Token、DNS 调用与连接失败排查

更新于 2026-11-05 · hgfastapp.lol

简答：Cloudflare API 的最快上手路径是：创建 API Token → 配置最小权限和资源范围 → 获取 account_id 或 zone_id → 用 Bearer Token 调用 v4 接口 → 根据 HTTP 状态码排查。新项目优先使用 API Token，不建议把 Global API Key 放进脚本或生产环境。本文按 2026-11-05 可访问的 Cloudflare 官方文档整理。

定义：Cloudflare API 是通过 HTTPS 接口自动管理账户、域名区域、DNS 记录及其他 Cloudflare 资源的程序化入口。

先用这 5 步完成第一次 Cloudflare API 调用

创建 Token：在 Cloudflare 控制台进入个人资料中的 API Tokens；如果使用账户级服务令牌，则进入对应账户的 API Tokens 页面。
选择权限：只授予任务需要的权限，例如查询 DNS 使用 Zone DNS Read，修改 DNS 才使用 DNS Write；不要为了省事直接授予全局编辑权限。
限定资源：将 Token 限定到指定账户、区域或其他资源。权限组和资源范围是两层控制，二者都要检查。
保存密钥：Token secret 通常只在创建完成时显示一次，应保存到环境变量或密钥管理工具，不要提交到 Git 仓库。
先验证再执行写入：先调用 Token 验证接口或读取接口，确认认证和权限都正常后，再执行 DNS 创建、修改或删除。

Cloudflare 官方文档说明，API 请求使用 Authorization: Bearer <API_TOKEN>，稳定的 v4 基础地址为 https://api.cloudflare.com/client/v4/。可参考创建 API Token 与发起 API 请求。

API Token、Account API Token 和 Global API Key 怎么选

认证方式	适用场景	权限控制	建议
用户 API Token	个人脚本、部署工具、日常自动化	可以按账户、区域、权限组和资源范围限制	大多数新项目优先选择
Account API Token	不希望令牌绑定到某个具体用户的服务或自动化	需确认目标接口是否兼容账户级 Token	适合服务间调用，但要先核对接口支持情况
Global API Key	旧脚本或暂时兼容旧认证方式的接口	权限通常等同于用户可执行的权限，范围较大	新项目尽量迁移到 API Token

Cloudflare 将 Global API Key 定位为旧式认证方式，并指出它不能像 API Token 一样细分资源、有效期或使用来源。现有旧脚本如果必须继续使用，应先确认接口文档要求，并制定迁移和轮换计划。相关说明见 API 入门、Global API Key 说明和 Token 创建指南。

如何获取 account_id 和 zone_id

zone_id 是某个域名区域的标识，DNS 记录接口通常需要它；account_id 是账户标识，账户级资源和部分过滤条件会使用它。不要把域名、账户名称或登录邮箱直接当成 ID。

在控制台中打开目标账户或域名区域，查看页面提供的 Account ID、Zone ID 字段。
也可以通过 API 查询区域列表。查询区域至少需要适合的 Zone Read 权限。
按域名过滤时，把域名放在查询参数中，并从返回的 result[].id 读取 zone_id；账户信息通常位于区域对象的 account.id。

示例：

curl "https://api.cloudflare.com/client/v4/zones?name=example.com" -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

区域列表接口支持按名称、账户、状态和分页参数筛选，具体字段以 List Zones API Reference 为准。官方查找路径也见 Find account and zone IDs。

第一个请求：验证 Token、查询 DNS、创建记录

1. 验证 Token 是否有效

curl "https://api.cloudflare.com/client/v4/user/tokens/verify" -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

成功响应通常包含 success: true，并在结果中返回 Token 状态。这个请求只能说明认证凭据有效，不能证明它拥有目标区域的 DNS 权限。

2. 查询某个区域的 DNS 记录

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?name=www.example.com" -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

查询 DNS 记录通常需要 DNS Read 或更高的相关权限。返回结果中的 result 是记录数组，分页信息位于 result_info。

3. 创建一条 A 记录

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json" --data '{"type":"A","name":"www.example.com","content":"198.51.100.10","ttl":3600,"proxied":false}'

创建记录需要 DNS Write 权限。示例中的 IP 地址只是文档示例地址，请替换为你确认过的源站地址。A、AAAA 与 CNAME 在相同名称下存在组合限制，写入前应查看接口校验结果和当前记录。

具体请求字段和权限要求以 List DNS Records 与 Create DNS Record 为准。

最小权限怎么配置才不容易遇到 403

只读脚本：例如监控 DNS，只申请 Zone DNS Read，不要申请 DNS Write。
更新 DNS：申请 DNS Write，并把资源范围限制为目标区域；如果脚本只服务一个域名，不要覆盖整个账户的所有区域。
账户级操作：使用账户资源权限时，确认 Token 的类型和具体接口兼容，不能仅凭“账户级”名称推断所有接口都能调用。
来源限制：如果任务运行在固定出口，可以考虑 IP 地址过滤；如果运行环境经常变化，不要在没有备用凭据和恢复方案时盲目加限制。
有效期和轮换：为临时任务设置合理 TTL；长期任务应准备新旧 Token 并行验证，再撤销旧 Token。

Cloudflare 的权限文档会区分 Account、User、Zone 等权限组，并对可用资源范围作说明。创建和轮换前请查看 API token permissions、Restrict tokens 和 Roll tokens。

Cloudflare API 常见报错排查表

现象	优先检查	处理方法
401 Unauthorized	Token 是否为空、过期、被撤销或 Bearer 写法错误	先重新检查环境变量，再调用 Token verify 接口；不要直接复制密钥到公开脚本。
403 Forbidden	权限组、资源范围、账户归属是否匹配	确认接口需要的权限，并检查 Token 是否限制到了错误的 zone 或 account。
DNS 请求返回权限不足	是否只有 Zone Read，却执行了写入	查询使用 DNS Read，创建、修改和删除才申请 DNS Write。
找不到区域或 zone_id 不匹配	域名是否属于当前账户，ID 是否复制完整	重新调用区域列表接口，按域名确认返回的 id 与 account.id。
429 或请求频率相关错误	是否短时间重复轮询、并发过高或没有退避	降低频率，使用分页和缓存，按响应提示增加退避；查看当前官方限制说明。
请求能通但结果为空	查询参数、分页、记录名称格式	先不加过滤参数测试，再逐个加入 name、page 和 per_page。

API 的 HTTP 状态码、错误数组和响应字段应结合具体接口文档判断。不要把“网络能连通”误认为“Token 有权限”；认证、授权、资源范围和参数校验是不同层次。

生产环境的密钥与网络检查清单

将 Token 放入环境变量、CI/CD Secret 或密钥管理服务，不写进前端代码、日志和公开仓库。
对写操作增加二次确认、变更记录和回滚方案，尤其是 DNS、路由和访问控制相关接口。
先用读取接口确认 account_id、zone_id 和当前记录，再执行写入；不要用盲目覆盖代替差异检查。
为请求记录时间、接口路径、HTTP 状态码和 Cloudflare 返回的错误信息，但不要记录完整 Token。
如果所有 API 请求都超时或出现连接失败，先检查本机 DNS、代理、MTU、防火墙和出口网络，再查看官方状态接口。

Cloudflare 提供程序化状态接口，常用的整体状态地址是 https://www.cloudflarestatus.com/api/v2/summary.json。官方建议自动化访问时使用可识别的 User-Agent，不要抓取状态页 HTML；详情见 Cloudflare Status API。截至 2026-11-05，本文只说明核验方法，不据此宣称服务当前无故障。

官方资料与核验范围

本文根据 2026-11-05 可访问的 Cloudflare 官方文档整理。已核对的内容包括 API Token 创建路径、Bearer 认证格式、v4 基础地址、区域和 DNS 接口、Global API Key 的限制、Token 权限与轮换方式，以及 Status API 的调用方式。具体接口所需权限、字段和账户条件可能随产品文档变化，执行生产变更前应再次打开对应接口页面核对。

常见问题

Cloudflare API Token 在哪里创建？

用户 Token 通常从 Cloudflare 控制台的个人资料 API Tokens 页面创建；账户级 Token 从对应账户的 API Tokens 页面创建。创建时选择模板或自定义权限，并限定资源范围。

Cloudflare API 为什么会返回 403？

最常见原因是 Token 没有目标接口要求的权限，或者 Token 虽有权限但没有覆盖当前 zone、account 或其他资源。先确认接口文档的权限要求，再检查 Token 的资源范围和 ID 是否属于同一账户。

Global API Key 能不能继续使用？

部分旧脚本可能仍能使用，但 Cloudflare 将它视为旧式认证方式。它的权限范围较大，难以按资源、来源和有效期细分；新项目更适合使用 API Token，旧项目应安排迁移和轮换。

只查询 DNS 记录需要 DNS Write 吗？

通常不需要。查询 DNS 记录应优先使用 DNS Read；只有创建、修改或删除记录等写入操作才需要 DNS Write。最终以当前接口文档列出的 Accepted Permissions 为准。

Cloudflare API 调用超时，是 Token 错了吗？

不一定。超时更像连接、DNS、代理、防火墙、MTU 或出口网络问题，但也可能发生在请求地址错误或环境变量未正确替换时。先用 curl 访问 API 基础地址并检查响应，再分别验证 Token、zone_id 和接口权限。