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/macOSexport CLOUDFLARE_API_TOKENtokenPowerShell$env:CLOUDFLARE_API_TOKEN tokenWindows CMDset CLOUDFLARE_API_TOKENtoken安全红线原文强调永远不要把 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_TOKENyour-token-here CLOUDFLARE_ACCOUNT_IDyour-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_tokenos.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_tokenos.environ[CLOUDFLARE_API_TOKEN], timeout120, # seconds (default 60) max_retries5, # default 2 base_urlhttps://..., # proxy (rare) ) # Per-request overrides client.with_options(timeout5, max_retries0).zones.get(zone_idzone-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」陷阱。三、核心配置项对照表仓库文档将三种语言的配置项整理为一张对照表这是跨语言迁移时最关键的速查依据OptionTypeScriptPythonGoDefaultTimeouttimeout(ms)timeout(s)WithRequestTimeout60sRetriesmaxRetriesmax_retriesWithMaxRetries2 (Go: 10)Base URLbaseURLbase_urlWithBaseURLapi.cloudflare.com注意Go SDK 的默认重试次数10 次明显高于 TypeScript/Python2 次因此在 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每个用户/Token1200 次请求 / 5 分钟全局每个 IP200 次请求 / 秒GraphQL320 次 / 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_TOKENtokenwrangler 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_TOKENaccount_id显式声明可避免多账号环境下选错账号也可以直接依赖环境变量。若你使用的是较新的 Wranglerv3.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 failedToken 过期/被吊销/未注入环境变量用client.user.tokens.verify()校验 Token确保CLOUDFLARE_API_TOKEN已设置403 ForbiddenToken 缺少权限scope 不足按操作申请对应 scope如 Zone:Edit、DNS:Edit、Workers Script:Edit重新创建 Token429 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:EditZone 级、部署 Worker 需要Workers Script:Edit账号级、读写 KV 分别需要Workers KV Storage:Read / Edit。八、参考链接api/configuration.md — 本文主文档环境变量、SDK 配置、Wrangler 集成api/api.md — 客户端初始化、认证API Token / API Key、自动分页、错误处理api/patterns.md — 批量并行、DNS 批量更新、错误恢复等实战模式api/gotchas.md — 速率限制、SDK 特有陷阱、限流参考表wrangler/auth.md — 认证决策树、CI/CD Token 创建、认证故障排查wrangler/configuration.md — wrangler.jsonc 格式、环境、路由、绑定进阶配置wrangler/README.md — Wrangler 安装与命令全集SKILL.md — cloudflare-deploy 技能的总体决策树与部署前置检查【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考