cloudflare-typescript 安装与 API Token 认证详解新手零踩坑连接 Cloudflare API 教程【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescriptcloudflare-typescript 是 Cloudflare 官方出品的 TypeScript SDKnpm 包名为cloudflare它让你用类型安全的代码直接调用 Cloudflare REST API——创建 Zone、管理 DNS、部署 Workers、操作 KV 全部一行搞定。本教程带你完成安装与 API Token 认证两大关键步骤全程零踩坑。为什么选择官方 SDK自己动手拼 HTTP 请求 手写 JSON 解析容易在分页、重试、超时这些细节上踩坑。官方 SDK 帮你把这些全部封装好了✅完整的 TypeScript 类型定义所有请求参数和响应字段都有类型提示IDE 悬停即可看文档✅自动重试网络抖动、429 限流、5xx 错误默认自动重试 2 次✅自动分页列表接口可用for await…of遍历所有页✅错误分类清晰401、403、404、429 各自对应不同的错误类型✅多运行时支持Node.js 20、Deno、Bun、Cloudflare Workers、浏览器均可运行客户端核心逻辑位于src/client.ts错误定义在src/core/error.ts想深入了解源码可以从这两个文件入手。快速安装 cloudflare-typescript要求环境TypeScript 4.9Node.js 20 LTS 及以上版本Deno 1.28 / Bun 1.0 也支持。在项目中执行以下命令即可npm install cloudflare 小贴士包名是cloudflare而不是cloudflare-typescript这是新手最容易搞错的一点。仓库名与 npm 包名不一致属于正常现象。安装完成后node_modules/cloudflare/dist/index.js即为入口文件同时提供 ESMindex.mjs和 CommonJSindex.js双格式import和require都能用。API Token 认证连接 Cloudflare API 的关键认证是整个流程中最容易报错的环节。官方推荐API Token而非老式的 Global API Key只需在 Cloudflare 控制台创建权限可以精确控制到某账号 某资源 只读/编辑安全性远高于全局密钥。方式一环境变量强烈推荐SDK 默认读取环境变量CLOUDFLARE_API_TOKEN见src/client.ts中的readEnv(CLOUDFLARE_API_TOKEN)这是官方示例脚本的标准用法例如examples/workers/script-upload.ts和examples/ai/demo.ts都是这样写的export CLOUDFLARE_API_TOKEN你的Token值之后创建客户端时什么都不用传import Cloudflare from cloudflare; const client new Cloudflare(); // 自动从环境变量读取 Token方式二代码中直接传入const client new Cloudflare({ apiToken: process.env[CLOUDFLARE_API_TOKEN], });两种方式效果完全一致SDK 会在每个请求头里加上Authorization: Bearer 你的Token拼接逻辑见src/internal/headers.ts。其他你可能用到的环境变量环境变量作用CLOUDFLARE_API_TOKENAPI Token 认证首选CLOUDFLARE_API_KEYCLOUDFLARE_EMAIL旧版 Global API Key 认证不推荐新使用CLOUDFLARE_BASE_URL覆盖默认 API 地址CLOUDFLARE_API_USER_SERVICE_KEYOrigin CA 证书 API 专用密钥CLOUDFLARE_LOG控制日志级别debug / info / warn / error / off新手常见报错速查遇到报错先对照这张表90% 的问题都能秒解报错原因解决AuthenticationError(401)Token 无效、被撤销或未配置检查CLOUDFLARE_API_TOKEN是否正确、是否在控制台被删除PermissionDeniedError(403)Token 权限不够重新创建 Token勾选对应资源权限如 Zone:WriteNotFoundError(404)account_id 或 zone_id 写错控制台核对 ID别把 Zone ID 填到 account_id 里RateLimitError(429)触发限流放心SDK 会默认自动重试 2 次APIConnectionError网络不通检查网络/代理可通过fetchOptions配置代理客户端常用配置一览除了认证这几个配置项能帮你少踩很多坑maxRetries失败重试次数默认 2 次设为 0 可关闭timeout单请求超时时间默认 1 分钟logLevel设为debug可打印完整请求与响应调试认证问题特别好用baseURL对接自建网关或测试环境时使用const client new Cloudflare({ logLevel: debug, // 调试时打开看到完整的请求日志 });第一次成功调用 API认证配置好之后用下面这段最小代码验证连通性——列出你的所有 Zoneimport Cloudflare from cloudflare; const client new Cloudflare(); const page await client.zones.list(); for (const zone of page.result) { console.log(zone.name, zone.id); }能打印出域名和 ID说明安装、认证全部成功 项目结构快速导航路径说明src/client.ts客户端主类认证与环境变量读取逻辑src/core/error.ts各类 API 错误定义src/core/pagination.ts自动分页实现src/resources/各产品Zones、KV、Workers 等API 封装examples/ai/demo.tsWorkers AI 调用示例examples/workers/script-upload.ts部署 Worker 的完整示例tests/按产品组织的完整测试用例可当用法手册读api.md全部 API 方法清单总结三步走告别踩坑npm install cloudflare→配置CLOUDFLARE_API_TOKEN环境变量→new Cloudflare()直接开调。记住包名与仓库名不同、401 查 Token、403 查权限你就能用官方 TypeScript SDK 快速打通 Cloudflare API 的自动化之旅。【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考