Cloudflare调用手册

按 URL 清除 CDN 缓存

发布静态资源后,清除指定地址的 Cloudflare 边缘缓存。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • Token 具备目标 Zone 的 Cache Purge 权限;域名已接入 Cloudflare 缓存链路。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

CLOUDFLARE_API_TOKEN
使用自定义 API Token,并限制到指定 Zone;不要使用 Global API Key。
CLOUDFLARE_ZONE_ID
域名 Overview 页的 Zone ID,或按本站获取 Zone ID 场景查询 result[].id;这里是虚构值。
终端
export CLOUDFLARE_API_TOKEN='replace_with_scoped_api_token'
export CLOUDFLARE_ZONE_ID='00000000000000000000000000000000'

以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    登录 Cloudflare 控制台 → My Profile → API Tokens → Create Token → Create Custom Token。

  2. 02

    Permissions 只添加 Zone → Cache Purge → Purge;Zone Resources 选择 Include → Specific zone → 你的域名。

  3. 03

    按需要限制客户端 IP、有效时间,确认摘要后生成;只在本地或服务器环境变量保存 CLOUDFLARE_API_TOKEN。

  4. 04

    获取 Zone ID。把示例 files 中的 URL 换成自己域名的真实静态资源完整地址,检查协议、主机名和查询串。

  5. 05

    确认源站已发布新文件,再提交清除。之后另行访问真实文件,检查内容与缓存状态。

调用 01

提交单文件清除

示例只清除一个明确 URL,不清空整个站点缓存。

POSThttps://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache

请求头

Authorization
Bearer ${CLOUDFLARE_API_TOKEN}
Content-Type
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
zone_idPathstring必填目标资源所属 Zone。
files请求体array必填本场景传完整 URL 字符串数组;若自定义缓存键使用请求头,需要改用含 url 和 headers 的对象。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
cat > request-body.json <<'JSON'
{
  "files": [
    "https://www.example.com/assets/app.js"
  ]
}
JSON

# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache")
headers = {
    "Authorization": expand("Bearer ${CLOUDFLARE_API_TOKEN}"),
    "Content-Type": expand("application/json"),
}
body = {
    "files": [
        "https://www.example.com/assets/app.js",
    ],
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "success" in result and result["success"] != True:
    raise SystemExit("平台返回业务错误,请结合下方排错说明检查响应")
Node.js
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${CLOUDFLARE_API_TOKEN}",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "files": [
    "https://www.example.com/assets/app.js"
  ]
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "success") && result["success"] !== true) {
  throw new Error('平台返回业务错误,请结合下方排错说明检查响应');
}

返回示例

按官方字段整理的响应结构示意,ID、文本和数字均为虚构,非接口实测结果。success=true 表示请求成功处理;result.id 不是新文件内容的校验值。 以下为结构示意,非本站实测结果。

JSON
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "33333333333333333333333333333333"
  }
}

常见错误与排查

HTTP 401 / 403认证或权限校验未通过。
核对 Bearer Token、资源范围、有效期与 IP 限制;读取返回 errors[].message 确认具体原因。
HTTP 429管理 API 触发限流。
遵守 retry-after,降低并发;全局额度与产品专属配额分别检查。
1134缓存清除专属频率上限已到。
按套餐的单文件 URL 吞吐降低速率,延迟重试;与全局管理 API 频控分开检查。
1092purge_everything 与其他清除字段同时传入。
本例只保留 files;不要混入 purge_everything。

调用注意

  • 单文件清除在全部套餐可用;当前 Free 每账号每秒 800 URL、每次最多 100 项,其他套餐配额不同。
  • 自定义 Cache Key 包含设备、国家、语言等头时,单纯字符串 URL 可能无法匹配,应按真实缓存键提交。
  • 清除不删除浏览器本地缓存,也不证明 Worker 代码、源站部署或文件内容已经更新。

注意事项

  • 一般管理 API 为每用户或账号 Token 每 5 分钟 1,200 次,另有每 IP 每秒 200 次限制;产品端点可能更严格。
  • 这里仅使用域名管理 API;套餐的 DNS/CDN 等资源规则继续适用,不把 Token 本身当成产品套餐。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
    Cloudflare 管理 API 限流核验日期 2026-10-15
  3. 03
    缓存清除可用性与配额核验日期 2026-10-15
  4. 04
    Purge Cached Content核验日期 2026-10-15

Cloudflare的其他调用手册

← 返回Cloudflare的全部功能