Cloudflare API 配置完全指南：环境变量、SDK 调参与 Wrangler 集成（cloudflare-deploy 技能库）-育师

Cloudflare API 配置完全指南：环境变量、SDK 调参与 Wrangler 集成（cloudflare-deploy 技能库）

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本指南以cloudflare-deploy技能库中的 references/api/configuration.md 为主体，系统讲解 Cloudflare API 的完整配置链路：从 API Token 环境变量的多平台注入方式，到 TypeScript / Python / Go 三种官方 SDK 的客户端初始化与超时、重试、Base URL 调参，再到 Wrangler CLI 与wrangler.toml的认证与部署集成。读完你将能正确、安全地配置 Cloudflare 客户端，规避 401/403/429 与超时陷阱，并能在 CI/CD 与本地开发两种场景下无缝切换认证方式。

一、环境变量：API 凭据的安全注入

1.1 三种平台下的环境变量设置

Cloudflare 官方 SDK 统一约定通过CLOUDFLARE_API_TOKEN环境变量读取 API Token。不同平台注入语法不同，仓库文档给出了完整对照：

平台	命令
Linux/macOS	`export CLOUDFLARE_API_TOKEN='token'`
PowerShell	`$env:CLOUDFLARE_API_TOKEN = 'token'`
Windows CMD	`set CLOUDFLARE_API_TOKEN=token`

安全红线（原文强调）：永远不要把 Token 提交进版本库。应使用.gitignore忽略的.env文件，或使用云厂商的密钥管理器（Secret Manager）。在 api/gotchas.md 的最佳实践中进一步补充了四条安全纪律：绝不提交 Token、使用最小权限、定期轮换 Token、为 Token 设置过期时间。

1.2 .env 文件模式

.env文件需要同时声明 API Token 与账号 ID，后者在 Zone 管理、Worker 部署等场景中必须使用：

# .env (add to .gitignore) CLOUDFLARE_API_TOKEN=your-token-here CLOUDFLARE_ACCOUNT_ID=your-account-id

在 TypeScript / Python 中加载.env并初始化客户端的标准写法如下：

// TypeScript import 'dotenv/config'; const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN, });

# Python from dotenv import load_dotenv load_dotenv() client = Cloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"])

注意 Python 侧使用os.environ["..."]时，若变量缺失会直接抛KeyError；若希望缺失时静默降级，可改用 api.md 中的os.environ.get("CLOUDFLARE_API_TOKEN")写法。部署前可用 wrangler/auth.md 提供的wrangler whoami验证凭据是否生效（未认证时该命令以非零退出码结束）。

二、SDK 客户端配置：三语言逐项拆解

2.1 TypeScript：毫秒级超时

const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN, timeout: 120000, // 2 min (default 60s), in milliseconds maxRetries: 5, // default 2 baseURL: 'https://...', // proxy (rare) }); // Per-request overrides await client.zones.get( { zone_id: 'zone-id' }, { timeout: 5000, maxRetries: 0 } );

要点：TypeScript 的timeout以毫秒为单位，maxRetries默认 2 次，baseURL仅在需要代理/镜像 API 网关时才配置。单请求级覆盖（per-request overrides）允许为特定操作临时收紧或放宽参数，适合「全局宽松、个别快速失败」的组合。

2.2 Python：秒级超时与链式覆盖

client = Cloudflare( api_token=os.environ["CLOUDFLARE_API_TOKEN"], timeout=120, # seconds (default 60) max_retries=5, # default 2 base_url="https://...", # proxy (rare) ) # Per-request overrides client.with_options(timeout=5, max_retries=0).zones.get(zone_id="zone-id")

Python 的timeout以秒为单位，with_options()返回一个应用了临时配置的新客户端实例，实现请求级覆盖而不污染全局客户端。若在异步代码中运行，应改用AsyncCloudflare（见 api.md 及 gotchas.md 中「sync 客户端无法 await」的典型报错）。

2.3 Go：函数式选项模式

client := cloudflare.NewClient( option.WithAPIToken(os.Getenv("CLOUDFLARE_API_TOKEN")), option.WithMaxRetries(5), // default 10 (higher than TS/Python) option.WithRequestTimeout(2 * time.Minute), // default 60s option.WithBaseURL("https://..."), // proxy (rare) ) // Per-request overrides client.Zones.Get(ctx, "zone-id", option.WithMaxRetries(0))

Go SDK 采用option.WithXxx函数式选项（functional options）模式，请求级覆盖通过给调用追加 option 实现。注意两点 Go 特性：其一，Go 默认重试为10 次（高于 TS/Python 的 2 次）；其二，可选字段必须用cloudflare.F()包装（区分零值、null 与省略），否则字段不会随请求发送——这是 gotchas.md 专门列出的「Go: Required Field Wrapper」陷阱。

三、核心配置项对照表

仓库文档将三种语言的配置项整理为一张对照表，这是跨语言迁移时最关键的速查依据：

Option	TypeScript	Python	Go	Default
Timeout	`timeout`(ms)	`timeout`(s)	`WithRequestTimeout`	60s
Retries	`maxRetries`	`max_retries`	`WithMaxRetries`	2 (Go: 10)
Base URL	`baseURL`	`base_url`	`WithBaseURL`	api.cloudflare.com

注意：Go SDK 的默认重试次数（10 次）明显高于 TypeScript/Python（2 次），因此在 Go 中编写快速失败（fast-fail）逻辑时，务必显式设置option.WithMaxRetries(0)或较小值，避免因默认重试导致响应延迟被放大。

四、超时配置：何时调大、如何拆分

默认超时 60 秒对于大多数 API 调用足够，但以下场景必须调大：

大型 Zone 迁移（zone transfers）
批量 DNS 操作
Worker 脚本上传

const client = new Cloudflare({ timeout: 300000, // 5 minutes });

gotchas.md 对超时错误给出了互补的工程建议：除调大超时外，还应拆分大操作——例如将 DNS 记录按每批 100 条切片，逐批processBatch处理，既降低单请求耗时，也避免触发速率限制：

const batchSize = 100; for (let i = 0; i < records.length; i += batchSize) { const batch = records.slice(i, i + batchSize); await processBatch(batch); }

五、重试配置：吞吐与快速失败的平衡

何时调大：以速率限制（429）为主的批处理工作流、网络不稳定的环境。何时调小：需要快速失败（fast-fail）的请求、面向用户的实时请求。

// Increase retries for batch operations const client = new Cloudflare({ maxRetries: 10 }); // Disable retries for fast-fail const fastClient = new Cloudflare({ maxRetries: 0 });

重试配置需要结合速率限制现实来理解。仓库文档记录的限流基线（见 gotchas.md 与 api/README.md）：

每个用户/Token：1200 次请求 / 5 分钟（全局）
每个 IP：200 次请求 / 秒
GraphQL：320 次 / 5 分钟（按成本计费）

SDK 遇到 429 时会自动以指数退避（exponential backoff）重试，并尊重Retry-After响应头；重试耗尽后才抛出RateLimitError。因此对「速率限制密集」的工作流调大maxRetries能显著提高成功率，但并发层面仍建议用p-limit等工具把并发控制在 10 以内（见 patterns.md 的受控并发示例与 gotchas.md 的 Limits Reference 表）。

六、Wrangler CLI 集成：从认证到部署

6.1 两种认证方式的选择

Wrangler 是 Cloudflare 官方 CLI（安装：npm install wrangler --save-dev）。认证方式按场景分流（决策树见 wrangler/auth.md）：

# 交互式 / 本地开发（推荐）：一次性 OAuth 登录 wrangler login # CI/CD 或 headless 环境：环境变量注入 API Token export CLOUDFLARE_API_TOKEN='token'

wrangler login会打开浏览器完成 OAuth，凭据保存在本地，后续所有命令自动生效；CI/CD 场景则应创建最小权限的 API Token（推荐使用 Dashboard 的「Edit Cloudflare Workers」模板，覆盖 Workers、Pages、KV、D1、R2），并设置CLOUDFLARE_API_TOKEN。

6.2 常用命令速查

以下命令均在底层调用 Cloudflare API，是 configuration.md 中 Wrangler 集成一节的完整命令集：

wrangler deploy # Uploads worker via API wrangler kv:key put # KV operations wrangler r2 bucket create # R2 operations wrangler d1 execute # D1 operations wrangler pages deploy # Pages operations # Get API configuration wrangler whoami # Shows authenticated user

在 cloudflare-deploy 技能的整体流程（SKILL.md）中，wrangler deploy、wrangler pages deploy等部署动作之前必须先验证认证：npx wrangler whoami若无法显示账号信息，则需回到wrangler login或设置环境变量。Wrangler 完整的资源管理与监控命令（KV/D1/R2/Secrets/wrangler tail等）可查阅 wrangler/README.md。

6.3 wrangler.toml 基础配置

name = "my-worker" main = "src/index.ts" compatibility_date = "2024-01-01" account_id = "your-account-id" # Can also use env vars: # CLOUDFLARE_ACCOUNT_ID # CLOUDFLARE_API_TOKEN

account_id显式声明可避免多账号环境下选错账号；也可以直接依赖环境变量。若你使用的是较新的 Wrangler（v3.91.0+），仓库在 wrangler/configuration.md 中推荐改用支持 schema 校验的wrangler.jsonc格式，并提供了$schema、vars、kv_namespaces、多环境（env.production）、路由（custom_domain/zone_name/workers_dev）、各类绑定（KV、D1、R2、Durable Objects、Queues、Hyperdrive、Workers AI 等）以及自动资源预置（auto-provisioning）等进阶配置的完整示例。

七、实战对照：配置错误的高发场景

将配置知识与常见故障对应起来，可以快速定位问题：

故障现象	根因	配置对策
`401 Authentication failed`	Token 过期/被吊销/未注入环境变量	用`client.user.tokens.verify()`校验 Token；确保`CLOUDFLARE_API_TOKEN`已设置
`403 Forbidden`	Token 缺少权限（scope 不足）	按操作申请对应 scope（如 Zone:Edit、DNS:Edit、Workers Script:Edit），重新创建 Token
`429 Rate limit`	超出 1200 次/5 分钟或 200 次/秒	调大`maxRetries`+ 应用层限流（`p-limit`，并发 ≤ 10）
请求超时（默认 60s）	大 Zone 迁移、批量 DNS、Worker 上传	调大`timeout`或按批次拆分操作
只取到 20 条结果	默认分页大小 20	使用`for await`自动分页迭代器遍历全部结果

其中 Token 所需权限对照表（列表见 gotchas.md）是排查 403 的关键依据：列 Zone 需要Zone:Read、创建 Zone 需要Zone:Edit（账号级）、编辑 DNS 需要DNS:Edit（Zone 级）、部署 Worker 需要Workers Script:Edit（账号级）、读写 KV 分别需要Workers KV Storage:Read / Edit。