企业官网建设流程全解析

cloudflare-typescript 安装与 API Token 认证详解：新手零踩坑连接 Cloudflare API 教程

【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript

cloudflare-typescript 是 Cloudflare 官方出品的 TypeScript SDK（npm 包名为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.9+，Node.js 20 LTS 及以上版本（Deno 1.28+ / Bun 1.0+ 也支持）。

在项目中执行以下命令即可：

npm install cloudflare

💡 小贴士：包名是cloudflare而不是cloudflare-typescript，这是新手最容易搞错的一点。仓库名与 npm 包名不一致，属于正常现象。

安装完成后，node_modules/cloudflare/dist/index.js即为入口文件，同时提供 ESM（index.mjs）和 CommonJS（index.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）。

其他你可能用到的环境变量

新手常见报错速查

遇到报错先对照这张表，90% 的问题都能秒解：

客户端常用配置一览

除了认证，这几个配置项能帮你少踩很多坑：

• maxRetries：失败重试次数，默认 2 次，设为 0 可关闭
• timeout：单请求超时时间，默认 1 分钟
• logLevel：设为'debug'可打印完整请求与响应，调试认证问题特别好用
• baseURL：对接自建网关或测试环境时使用

const client = new Cloudflare({ logLevel: 'debug', // 调试时打开，看到完整的请求日志 });

第一次成功调用 API

认证配置好之后，用下面这段最小代码验证连通性——列出你的所有 Zone：

import 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，说明安装、认证全部成功 🎉

项目结构快速导航

总结

三步走，告别踩坑：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