Cloudflare API接口调用教程｜适合跨境电商

跨境电商网站通常面向全球用户，业务涉及多地区访问、支付、物流查询、营销活动、独立站建站、品牌官网、ERP系统对接等场景。对于这类网站来说，访问速度、稳定性、安全防护和自动化运维能力非常重要。

Cloudflare 作为全球知名的 CDN、DNS、WAF 和边缘网络服务平台，很多跨境电商卖家都会使用它来管理域名解析、加速网站访问、防护恶意攻击、配置 SSL 证书、清理缓存等。而 Cloudflare API 则可以帮助我们将这些操作自动化，例如：

• 自动添加或修改 DNS 解析记录；
• 批量清理 CDN 缓存；
• 查询域名 Zone 信息；
• 自动配置页面规则或缓存规则；
• 配合独立站后台、ERP、CI/CD 系统实现自动部署；
• 监控域名状态、安全事件和访问情况；
• 为多个品牌站、多个店铺域名做统一管理。

本文将从跨境电商实际应用角度，系统介绍 Cloudflare API 的基础概念、Token 创建方法、常用接口调用方式，以及适合卖家的典型自动化场景。

一、为什么跨境电商需要使用 Cloudflare API？

很多卖家最开始使用 Cloudflare，只是为了做域名解析或开启 CDN 加速。但当业务规模扩大后，手动操作会变得低效。

例如你可能会遇到这些情况：

1. 多个独立站域名需要统一管理
   比如一个卖家同时运营美国站、欧洲站、澳洲站，或者多个品牌站，每个域名都要配置 DNS、SSL、缓存策略和安全规则。

2. 网站频繁上新或更新页面，需要清理缓存
   Shopify、WooCommerce、Shopline、自建站等平台在更新首页、商品页、活动页后，如果 CDN 缓存未及时刷新，用户可能看到旧内容。

3. 服务器迁移时需要快速修改 DNS
   跨境电商在黑五、圣诞节等大促前，可能会升级服务器或迁移节点。通过 API 可以快速批量修改解析记录。

4. 需要和内部系统联动
   例如 ERP 系统、自动部署系统、监控系统，可以调用 Cloudflare API 自动完成运维动作。

5. 安全防护需要自动化响应
   当检测到异常流量、恶意 IP 或爬虫攻击时，可以通过 API 动态调整安全规则或封禁 IP。

因此，Cloudflare API 不仅适合技术团队使用，也非常适合有一定技术基础的跨境电商运营团队、独立站卖家和建站服务商。

二、Cloudflare API 基础概念

在正式调用接口之前，需要了解几个核心概念。

1. Account

Account 是 Cloudflare 账户级别的概念。一个账户下面可以管理多个域名，也就是多个 Zone。

例如你的 Cloudflare 账户中可能有以下域名：

• example.com
• brand-store.com
• us-shop.com
• eu-shop.com

这些域名都属于你的 Cloudflare Account。

2. Zone

Zone 通常指一个域名在 Cloudflare 中的管理区域。
例如：

example.com

就是一个 Zone。

大多数 Cloudflare API 操作都需要使用 zone_id，比如查询 DNS 记录、修改 DNS、清理缓存等。

3. DNS Record

DNS Record 指域名解析记录，包括：

跨境电商中最常用的是 A、CNAME、TXT、MX。

4. API Token

API Token 是调用 Cloudflare API 的身份凭证。
相比旧版 Global API Key，API Token 更安全，因为它可以限制权限范围。

比如你可以创建一个 Token，只允许：

• 读取某个域名信息；
• 修改某个域名 DNS；
• 清理某个 Zone 的缓存；
• 不能访问其他域名或账户设置。

对于跨境电商来说，建议优先使用 API Token，而不是 Global API Key。

三、创建 Cloudflare API Token

下面介绍如何在 Cloudflare 后台创建 API Token。

第一步：登录 Cloudflare 后台

访问：

https://dash.cloudflare.com/

登录你的 Cloudflare 账户。

第二步：进入 API Tokens 页面

点击右上角头像，进入：

My Profile > API Tokens

然后点击：

Create Token

第三步：选择模板或自定义权限

Cloudflare 提供了多个模板，例如：

• Edit zone DNS
• Read analytics and logs
• Edit Cloudflare Workers
• Purge cache

如果只是为了管理 DNS，可以选择：

Edit zone DNS

如果要自定义权限，可以选择：

Create Custom Token

第四步：配置权限

例如我们要允许 Token 管理某个域名的 DNS，可以这样配置：

Permissions:
Zone - DNS - Edit
Zone - Zone - Read

资源范围选择：

Include - Specific zone - example.com

这样这个 Token 只能管理 example.com 的 DNS，不会影响账户下其他域名。

第五步：生成并保存 Token

点击生成后，Cloudflare 会显示一串 Token，例如：

abc123xxxxxxxxxxxxxxxxxxxxxxxx

注意：Token 只会完整显示一次，请务必安全保存。

建议保存到：

• 服务器环境变量；
• 密钥管理系统；
• CI/CD Secret；
• 本地加密文档。

不要将 Token 写入公开代码仓库，也不要直接暴露在前端网页中。

四、Cloudflare API 请求格式

Cloudflare API 的基础地址是：

https://api.cloudflare.com/client/v4

调用时通常需要在请求头中加入：

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

例如使用 curl 调用：

curl -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Cloudflare API 返回结果通常是 JSON 格式，结构大致如下：

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

其中：

• success：是否调用成功；
• errors：错误信息；
• messages：提示信息；
• result：主要数据内容。

五、查询 Zone ID

很多接口都需要 zone_id。因此第一步通常是查询域名对应的 Zone ID。

示例：查询域名 Zone 信息

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

返回示例：

{
  "success": true,
  "result": [
    {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com",
      "status": "active",
      "paused": false,
      "type": "full"
    }
  ]
}

这里的：

023e105f4ecef8ad9ca31a8372d0c353

就是 zone_id。

在后续调用 DNS、缓存、安全规则等接口时，都需要使用它。

六、查询 DNS 解析记录

假设我们要查询 example.com 下的所有 DNS 记录，可以使用以下接口：

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

如果只查询某个子域名，比如 www.example.com：

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records?name=www.example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

返回示例：

{
  "success": true,
  "result": [
    {
      "id": "dns_record_id",
      "type": "CNAME",
      "name": "www.example.com",
      "content": "example.com",
      "proxied": true,
      "ttl": 1
    }
  ]
}

其中：

• id：DNS 记录 ID；
• type：记录类型；
• name：域名；
• content：解析目标；
• proxied：是否开启 Cloudflare 代理；
• ttl：缓存时间，1 通常表示自动。

七、新增 DNS 解析记录

跨境电商常见场景：
你新建了一个活动页、落地页或子站点，比如：

sale.example.com

需要解析到服务器 IP：

203.0.113.10

可以通过 API 新增 A 记录。

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "A",
    "name": "sale.example.com",
    "content": "203.0.113.10",
    "ttl": 1,
    "proxied": true
  }'

字段说明：

如果 proxied 设置为 true，表示开启橙云代理，流量会经过 Cloudflare。
如果设置为 false，表示仅使用 DNS 解析，不走 CDN。

对于跨境电商网站主站，通常建议开启代理；但对于某些第三方验证、邮件服务、支付回调域名，需要根据服务商要求决定是否开启。

八、修改 DNS 解析记录

服务器迁移时，经常需要修改 A 记录 IP。
修改 DNS 记录需要先拿到该记录的 dns_record_id。

1. 查询记录 ID

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records?name=www.example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

找到返回结果中的：

id

2. 修改 DNS 记录

curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/DNS_RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "A",
    "name": "www.example.com",
    "content": "198.51.100.20",
    "ttl": 1,
    "proxied": true
  }'

这个操作会将 www.example.com 解析到新的服务器 IP。

跨境电商在大促前进行服务器扩容或迁移时，可以用这个接口快速切换流量。

九、删除 DNS 解析记录

如果某个测试站、旧活动页或临时子域名已经不用，可以删除对应 DNS 记录。

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/DNS_RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

注意：删除 DNS 记录前一定要确认该域名没有正在使用，避免影响用户访问、广告落地页或支付回调。

十、清理 Cloudflare 缓存

对于跨境电商网站来说，缓存清理是非常重要的操作。

常见情况包括：

• 首页 Banner 更新；
• 商品价格调整；
• 黑五、圣诞节活动页上线；
• 商品详情页图片替换；
• SEO 页面内容更新；
• CSS、JS 文件发布新版本；
• 促销倒计时组件修改。

如果缓存没有及时刷新，用户可能看到旧价格、旧库存或旧活动内容，从而影响转化率。

1. 清理全部缓存

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "purge_everything": true
  }'

这种方式会清理整个 Zone 的缓存。

不过不建议频繁使用，因为全部清理后，短时间内大量请求会回源，可能增加服务器压力。

2. 按 URL 清理缓存

更推荐的方式是指定 URL 清理。

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "files": [
      "https://www.example.com/",
      "https://www.example.com/products/sample-product",
      "https://www.example.com/collections/black-friday"
    ]
  }'

这种方式适合商品页、活动页、博客页、首页等内容更新。

3. 按标签清理缓存

如果你的网站后端支持给缓存资源加 Cache Tag，也可以通过标签清理。

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "tags": [
      "product-1001",
      "collection-black-friday"
    ]
  }'

这种方式适合大型独立站或自建电商平台。

十一、使用 Python 调用 Cloudflare API

除了 curl，也可以用 Python 编写脚本，适合批量操作。

下面示例演示如何查询 DNS 记录。

import requests

API_TOKEN = "YOUR_API_TOKEN"
ZONE_ID = "YOUR_ZONE_ID"

url = f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/dns_records"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()

if data.get("success"):
    for record in data.get("result", []):
        print(record["type"], record["name"], record["content"])
else:
    print("API调用失败：", data.get("errors"))

Python 示例：自动清理指定页面缓存

import requests

API_TOKEN = "YOUR_API_TOKEN"
ZONE_ID = "YOUR_ZONE_ID"

urls = [
    "https://www.example.com/",
    "https://www.example.com/products/new-arrival",
    "https://www.example.com/collections/summer-sale"
]

api_url = f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/purge_cache"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

payload = {
    "files": urls
}

response = requests.post(api_url, headers=headers, json=payload)
result = response.json()

if result.get("success"):
    print("缓存清理成功")
else:
    print("缓存清理失败：", result.get("errors"))

这个脚本可以集成到网站后台，例如运营人员发布活动页后，自动调用接口清理缓存。

十二、适合跨境电商的典型 API 自动化场景

场景一：商品更新后自动清理缓存

如果你的独立站是自建系统，可以在商品更新接口中增加逻辑：

1. 运营人员修改商品价格或描述；
2. 系统保存商品数据；
3. 自动生成商品页 URL；
4. 调用 Cloudflare API 清理该商品页缓存；
5. 用户访问时看到最新内容。

这样可以避免用户看到旧价格，减少客服纠纷。

场景二：大促活动页自动刷新

黑五、网一、圣诞节、新年促销期间，活动页面经常调整。
可以将缓存清理脚本接入发布流程：

活动页发布 -> 自动构建前端页面 -> 上传服务器 -> 调用 Cloudflare API 清理缓存

这样运营团队不需要每次登录 Cloudflare 后台手动清理。

场景三：多品牌站批量管理 DNS

如果你管理多个品牌站，例如：

brand-a.com
brand-b.com
brand-c.com

可以把域名、Zone ID、DNS 记录信息存入配置文件，然后用脚本批量新增、修改或检查解析。

适合以下团队：

• 跨境电商集团；
• 多店铺卖家；
• 建站服务商；
• 代运营团队；
• SaaS 工具服务商。

场景四：服务器迁移自动切换解析

大促前，卖家可能会将网站迁移到更高配置服务器。
可以提前写好脚本，迁移完成后执行：

1. 修改 A 记录到新 IP；
2. 开启代理；
3. 清理缓存；
4. 检测网站访问状态；
5. 发送通知给运维或运营团队。

这样可以降低人工操作失误。

场景五：异常流量时自动提升安全等级

如果网站遭遇恶意请求、撞库、爬虫抓取或 DDoS 攻击，可以通过 Cloudflare 的安全相关 API 自动调整策略。

例如：

• 提高 Security Level；
• 开启 Under Attack Mode；
• 增加防火墙规则；
• 封禁异常 IP；
• 结合日志系统做自动响应。

不过安全策略配置需要谨慎，避免误伤正常用户，尤其是来自美国、欧洲、东南亚等主要市场的真实买家。

十三、API 调用安全建议

Cloudflare API 权限很高，如果管理不当，可能导致 DNS 被恶意修改、缓存被错误清理，甚至影响整个网站访问。因此建议遵守以下安全原则。

1. 使用最小权限原则

只给 Token 必要权限。

例如只需要清理缓存，就不要给 DNS 编辑权限。
只管理一个域名，就不要授权全部域名。

2. 不要把 Token 写入前端代码

错误示例：

const token = "YOUR_API_TOKEN";

如果这样写在浏览器端，任何用户都可能看到 Token。

正确做法是：

• 后端服务器调用 Cloudflare API；
• 前端只请求你自己的后端接口；
• Token 保存在服务器环境变量中。

3. 定期轮换 Token

建议定期更换 API Token，尤其是：

• 员工离职；
• 外包合作结束；
• 代码仓库曾经泄露；
• 服务器被入侵；
• 发现异常 API 操作。

4. 为不同系统创建不同 Token

例如：

这样即使某个 Token 泄露，影响范围也可控。

5. 记录 API 操作日志

如果你的系统允许运营人员通过后台清理缓存或修改 DNS，建议记录：

• 操作人员；
• 操作时间；
• 操作类型；
• 目标域名；
• 请求参数；
• 返回结果。

这对排查问题非常有帮助。

十四、常见错误与排查方法

1. 返回 401 Unauthorized

可能原因：

• Token 错误；
• Token 已失效；
• 请求头格式错误；
• 没有使用 Bearer。

正确格式：

Authorization: Bearer YOUR_API_TOKEN

2. 返回 403 Forbidden

可能原因：

• Token 权限不足；
• 没有授权对应 Zone；
• 当前接口需要更高权限。

解决方法：

检查 API Token 权限，例如是否包含：

Zone - DNS - Edit
Zone - Zone - Read

3. 找不到 DNS 记录

可能原因：

• 查询的域名不完整；
• 使用了错误的 Zone ID；
• 记录不存在；
• 子域名拼写错误。

建议使用完整域名查询：

www.example.com

而不是只写：

www

4. 缓存清理后仍看到旧内容

可能原因：

• 浏览器本地缓存；
• 源站缓存；
• 电商平台自身缓存；
• URL 不一致；
• 页面中资源文件仍被缓存；
• 多语言或多地区页面路径不同。

解决方法：

• 使用无痕模式测试；
• 检查源站缓存；
• 清理具体 URL；
• 检查是否有带参数的页面；
• 对 CSS/JS 使用版本号。

5. DNS 修改后没有立即生效

虽然 Cloudflare DNS 通常生效很快，但仍可能受以下因素影响：

• 本地 DNS 缓存；
• 运营商递归 DNS 缓存；
• 浏览器缓存；
• 原 TTL 设置；
• 第三方服务缓存。

可以使用以下命令测试：

dig www.example.com

或使用在线 DNS 查询工具检查全球解析结果。

十五、跨境电商使用 Cloudflare API 的最佳实践

1. 主站开启 Cloudflare 代理

对于独立站主域名和 www 域名，通常建议开启 Cloudflare 代理，这样可以使用 CDN、WAF、缓存、安全防护等能力。

例如：

example.com
www.example.com

可以设置：

"proxied": true

2. 邮件相关记录不要随意代理

MX、SPF、DKIM、DMARC 等邮件相关记录通常不需要代理。
例如：

mail.example.com

如果是邮件服务器记录，需要根据邮箱服务商文档配置。

3. 支付和第三方验证域名谨慎配置

有些支付服务商、物流服务、广告平台验证要求 DNS 记录必须保持特定格式。
在修改前应查看官方文档，避免影响支付回调、广告验证或网站认证。

4. 缓存策略要区分页面类型

跨境电商网站中，不同页面适合不同缓存策略：

不要盲目全站缓存，否则可能导致用户看到错误的购物车、价格或订单信息。

5. 大促前进行 API 脚本演练

在黑五、网一等大促前，建议提前测试：

• DNS 修改脚本；
• 缓存清理脚本；
• 回滚脚本；
• 安全策略调整脚本；
• 监控报警脚本。

不要等到正式活动开始后才第一次运行脚本。

十六、一个简单的完整流程示例

假设你的跨境电商网站要上线一个黑五活动页：

https://www.example.com/collections/black-friday

推荐流程如下：

1. 开发或运营完成活动页配置；
2. 发布页面到线上环境；
3. 调用 Cloudflare API 清理该 URL 缓存；
4. 访问页面确认内容正确；
5. 检查移动端、PC 端、多地区访问；
6. 如果页面异常，回滚内容并再次清理缓存；
7. 活动结束后更新页面或下线页面；
8. 再次清理缓存。

对应 API 请求：

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "files": [
      "https://www.example.com/collections/black-friday"
    ]
  }'

这个流程虽然简单，但对跨境电商转化率非常重要。尤其在促销活动中，页面展示错误可能直接造成订单损失。

十七、总结

Cloudflare API 对跨境电商来说，不只是技术工具，更是提升网站运维效率和稳定性的关键能力。

通过 Cloudflare API，你可以实现：

• 自动查询和管理 DNS；
• 快速切换服务器解析；
• 批量清理 CDN 缓存；
• 配合活动页发布自动刷新；
• 管理多个品牌站域名；
• 与监控、安全系统联动；
• 降低人工操作风险。

对于刚开始使用的卖家，建议先从以下三个接口入手：

1. 查询 Zone ID；
2. 查询和修改 DNS 记录；
3. 清理指定 URL 缓存。

等熟悉后，再逐步扩展到安全规则、分析数据、Workers、页面规则等高级能力。

最后提醒：Cloudflare API Token 一定要妥善保管，并遵循最小权限原则。对于跨境电商而言，域名和网站访问稳定性直接关系到广告投放、用户转化和订单收入，任何 API 自动化操作都应经过测试、记录和权限控制。