AI 编程时代的 Cloudflare 实战手册

这是一份面向 AI 编程时代的 Cloudflare 实战手册。Cloudflare 的功能模块、AI 编程工作流、计费额度、开源项目、避坑指南和国内访问注意事项，都在这里按实际使用场景整理清楚。

功能模块

Cloudflare 的能力可以按站点基础、计算、数据存储、AI、媒体、安全、观测七类理解。每个模块说清楚什么时候你会用到、坑在哪。

站点基础

DNS：权威 DNS 服务，负责把域名指向网站、API、邮箱等资源。买了域名后通常先把 NS 改到 Cloudflare，之后 A、AAAA、CNAME、MX、TXT 这些记录都在这里配，子域名、邮箱验证、CNAME flattening、DNSSEC 也都属于这一层。

SSL/TLS：浏览器到 Cloudflare、Cloudflare 到源站之间的 HTTPS 加密。接入 Cloudflare 后，边缘证书通常会自动签发和续期；如果有自建源站，要注意加密模式。普通静态站和 Workers 项目基本不用折腾证书链。

Cache / CDN：静态资源、页面和部分响应的全球边缘缓存。静态资源、图片、构建后的 JS/CSS 最适合走缓存；登录后的个人数据、实时接口、带权限的响应不要乱缓存。

Rules：重定向、缓存、Header、源站、配置覆盖的规则系统。想把旧域名 301 到新域名、给某些路径加安全 Header、控制缓存策略、改写 URL、把不同路径转到不同源站，优先看 Rules。

计算

Workers：Cloudflare 的 serverless 运行时，用来跑 JS/TS、Wasm、部分 Python 等后端逻辑。AI 生成的 Hono API、鉴权接口、Webhook、BFF、MCP Server、轻量 AI 编排，基本都可以放到 Workers。它适合短请求和高并发边缘逻辑。

Workers Static Assets：Worker 项目里的静态资源托管，把前端文件和 Worker 代码作为一个整体部署。AI 生成 Vite、React、Vue、Svelte、静态文档站或带 API 的前端项目时，这个很顺。

Pages：面向前端项目的部署平台，主打 Git 集成、预览部署和静态站发布。连上 GitHub/GitLab 后，push 就能构建和发布，适合官网、博客、文档站、活动页、原型页面。

Durable Objects：有状态对象，适合需要强一致协调、会话状态和 WebSocket 的场景。Workers 本身是无状态的，但聊天房间、协作画板、在线游戏房间、计数器、Agent 会话都需要一个"同一时间说了算"的地方。

Workflows：持久化的多步骤任务，用来跑会失败、会等待、会重试的流程。AI 生成的业务经常不是一次请求能做完：先调 API，再写库，再发邮件，再等人工确认，最后发布结果。

Queues：异步消息队列，用来保证任务投递、削峰、批处理和重试。有些事不该让用户等：发邮件、处理上传文件、写审计日志、批量同步数据、触发后台生成。

Containers：在 Cloudflare 上跑容器，适合 Workers 跑不了的语言、库和长进程。如果 AI 生成的项目依赖系统库、长时间进程、传统 HTTP 服务、原生二进制，Containers 是更自然的选择。

Cron Triggers：按 cron 表达式定时触发 Worker 的计划任务。每小时同步一次数据、每天清理一次 D1、定时刷新缓存、周期性检查第三方 API，都可以用 Cron Triggers。

数据存储

D1：Cloudflare 托管的 serverless SQL 数据库，语法接近 SQLite。AI 生成应用时，用户、订单、文章、配置这些结构化数据可以优先放 D1。

KV：全球分布式键值存储，适合读多写少、低延迟读取的数据。配置、短链映射、feature flag、缓存结果、边缘读取的小块 JSON，都适合 KV。

R2：S3 兼容对象存储，用来存文件、图片、视频、附件、备份和数据集。AI 编程里一碰到用户上传、图片托管、导出文件、备份文件，先想到 R2。

Hyperdrive：连接外部 Postgres/MySQL 的边缘连接池和查询加速层。如果数据库已经在 Supabase、Neon、RDS、自建 Postgres/MySQL，不想迁移，但 Worker 访问数据库又怕连接慢、连接数爆掉，就用 Hyperdrive。

Vectorize：Cloudflare 的向量数据库，用来存 embedding 并做相似度检索。做 RAG、语义搜索、相似推荐时会用到它。

DO Storage：Durable Objects 自带的持久化存储，跟某个对象实例绑定，用来保存这个对象的状态。

Secrets Store：集中管理密钥和敏感配置。API Key、Webhook secret、数据库密码、第三方服务 token，不应该写在代码里。

Pipelines：把事件流和日志持续写入目标存储的数据管道。当你有持续产生的数据，比如应用事件、行为日志、分析事件，需要稳定写到 R2 等地方做后续分析，就看 Pipelines。

AI

Workers AI：Cloudflare 的 serverless AI 推理平台。可以从 Worker、Pages 或 REST API 调用 Cloudflare 托管的模型，做 LLM、embedding、文本分类、语音转文字、图片理解等任务。

AI Gateway：AI API 的统一网关，负责观测、缓存、限流和成本控制。同时用 OpenAI、Anthropic、Workers AI、Groq、Mistral 这类 provider 时，先接 AI Gateway。

AI Search：Cloudflare 托管的 AI 搜索能力。如果想快速给网站、文档、知识库加语义搜索和问答体验，可以看 AI Search。

Agents SDK：构建有状态 AI Agent 的框架，底层基于 Durable Objects。做多轮对话、工具调用、Agent 记忆、实时 WebSocket、定时任务时，用 Agents SDK 比自己手写状态管理舒服。

媒体

Images：图片托管、优化、变体和边缘转换服务。如果项目里有用户头像、商品图、封面图、内容配图，Images 可以负责上传、存储、压缩、裁剪、格式转换和按需生成不同尺寸。

Stream：视频存储、编码、播放和分发服务。上传视频后，Stream 负责转码、生成自适应码流、托管播放器和全球分发。

Realtime：实时音视频和低延迟通信能力。做多人会议、语音房、直播连麦、实时互动时会碰到它。

Browser Rendering：在 Workers 里调用无头浏览器进行渲染、截图和自动化。需要把网页转成截图、生成 PDF、跑页面渲染检查、抓取自己可访问页面的最终 DOM 时，可以用 Browser Rendering。

安全

Turnstile：Cloudflare 的验证码替代方案，用来判断请求是不是来自真实用户。登录、注册、评论、表单、试用申请都能接 Turnstile。

Access：Zero Trust 里的应用访问控制，给内部工具和后台加身份验证。你做了一个 admin 后台、内部数据看板、临时运维工具，不想自己写登录系统，就用 Access。

WAF：Web 应用防火墙，在请求到达应用前拦截常见攻击。AI 生成的代码可能有低级安全问题，WAF 能做一层边缘兜底。

Rate Limiting：按路径、IP、Header、请求特征限制访问频率。登录接口、短信验证码、公开 API、AI 调用入口、上传接口，都应该考虑限流。

DDoS 防护：Cloudflare 网络层和应用层的 DDoS 防护，会在边缘网络自动吸收和缓解大量攻击流量。

API Shield：面向 API 的安全能力集合，包括 schema 校验、mTLS、发现和滥用检测。

观测

Log Explorer：Cloudflare Dashboard 里的日志搜索工具。线上请求出问题时，先看这里。

Trace：模拟请求经过 Cloudflare 配置后的处理路径，适合验证配置为什么这样生效。

Observability：Workers 和 Pages 的运行观测入口，看请求量、错误率、延迟、异常日志、部署版本表现。

Logpush：把 Cloudflare 日志持续推送到外部目的地，需要长期留存日志、接入 SIEM、放到 R2/S3/BigQuery/Splunk 等系统分析时用。

Web Analytics：隐私友好的站点访问和前端性能分析，看页面访问量、来源、国家地区、设备、Web Vitals。

Analytics Engine：Workers 里的自定义指标和事件分析引擎，写入业务事件后再用 SQL 聚合分析。

AI 编程工作流

AI 写 Cloudflare 代码最容易翻车的地方不是语法，而是它根本不知道 Cloudflare 有什么、边界在哪。解决办法很简单：先给 AI 配好 Cloudflare 的"说明书"和"工具箱"。

三分钟搞定

用 Codex（OpenAI 官方客户端）：

bash

cd your-cloudflare-project
codex

进入 Codex 后输入 /plugins，搜索 Cloudflare，回车安装。完成配置。

用 Claude Code（Anthropic 官方客户端）：

bash

cd your-cloudflare-project
claude

进入 Claude Code 后依次输入这两行：

text

/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare

效果跟 Codex 那边一样。

这些东西分别是干嘛的

Skill = 说明书：帮助 AI 理解 Cloudflare 怎么开发。Workers、Pages、R2、D1、KV、Queues、Durable Objects、Agents SDK、Wrangler、Email 这些它都会写。
MCP = 连接器：让 AI 能连你的 Cloudflare 账号和官方文档。Docs MCP 默认开，Cloudflare API MCP 要上线改配置时再开，Observability MCP 排查问题时开。
Wrangler = 真正干活的命令行工具：Skill 和 MCP 都是帮助 AI 理解，真正要在电脑上跑起来、部署上线，还得靠 Wrangler。

bash

npm i -D wrangler@latest
npx wrangler dev      # 本地跑起来
npx wrangler deploy   # 部署上线
npx wrangler tail     # 看实时日志

常见架构模式

模式一：Worker + D1 + R2（全栈应用）

Client → Worker → D1（元数据/用户/订单） + R2（文件/图片/附件） + KV（配置/缓存）

适用场景：SaaS 原型、内容管理、API 服务。

模式二：Workers Static Assets + Worker（前后端一体）

Client → Static Assets（HTML/CSS/JS/图片） + /api/* → Worker → D1 / R2

适用场景：React/Vue/Svelte 前端 + API 后端。静态资源请求免费且不计入 Workers 配额。

模式三：Worker + Durable Objects + WebSocket（实时协作）

WebSocket 客户端 A/B/C → Durable Object（房间/会话状态） → DO SQLite Storage

适用场景：聊天室、协作编辑、在线游戏、实时看板。

模式四：Worker + Queues + Workflows（异步处理）

Worker API → Queues → Consumer Worker → Workflows（多步骤持久化） → D1 / Email Sending

适用场景：订单处理、数据管道、AI 审核流、用户生命周期邮件。

模式五：Worker + AI Gateway + 外部模型（AI 应用）

Client → Worker → AI Gateway → OpenAI / Anthropic / Workers AI + Vectorize + R2 原文存储

适用场景：AI 聊天、RAG 问答、多模型路由。

AI 编程 Cloudflare 常见翻车点

用 Node.js 思维写 Worker：AI 经常生成 require('fs')、express()、http.createServer() 等 Node.js 代码。Workers 不是 Node.js，正确做法是使用 Web 标准 API 和 Hono 等 Workers 原生框架。
把 binding 当环境变量：正确写法是 env.MY_KV.get(key) 或 env.DB.prepare(sql)，不是 process.env.MY_KV。
忽略浮动 Promise：未 await 的异步调用在 Workers 里会被静默丢弃，每个异步操作要么 await，要么传给 ctx.waitUntil()。
全局变量存请求状态：Workers 会复用 isolate，模块级变量在不同请求间共享，会导致数据泄漏。
不知道 Static Assets 请求免费：不要把所有请求都路由到 Worker，静态资源直接由 Static Assets 处理。
用 REST API 调自家 R2：从 Worker 内应该使用 R2 binding（env.MY_BUCKET.get(key)），零网络跳、零认证、零额外延迟。

计费与额度

Cloudflare 的"免费"不是一种口径。有的服务达到 Free 上限后直接报错，有的服务 Free 可用、Paid 后继续按量计费，有的服务不按用量计费，而是跟随域名套餐、Zero Trust 计划或单独产品开通。

先搞懂额度怎么算

额度按不同级别算。有的按账号，有的按域名，有的按站点。
按天和按月不能直接换算。Workers、D1、KV 是 /天，R2、Vectorize 是 /月。
有些服务共享同一个池。Workers、Pages Functions、Workflows、Cron 触发后的请求共享同一个 10 万/天。
超出后有两种结果：报错型（不会扣钱）和自动收费型（会扣钱）。R2 超出 10 GB 存储后按 $0.015/GB 自动计费，没有开关可以关。
额度不一定能叠加。R2 的 10 GB 和 Workers $5 套餐完全无关。

免费能扛多少真实量

典型场景	免费额度是否充足	可承载规模参考
静态博客 / 文档站	充足	Pages 静态请求免费无限
独立 SaaS 原型	充足（验证阶段）	日活 1000 用户、每人每天 10 次请求 ≈ 1 万请求/天
图床 / 文件分享	起步阶段充足	R2 10 GB ≈ 1 万张 1 MB 图片
短链服务	小规模充足	KV 1 GB ≈ 100 万条 1KB 映射
AI 聊天 / RAG	很快撞墙	Workers AI 1 万 Neurons/天 ≈ 几十到几百次对话
域名邮箱	无限免费	Email Routing 不限收信量
Webhook 接收器	充足	Workers 10 万请求/天接 GitHub / Stripe webhook 绰绰有余
定时任务	小规模可用	Free 仅 5 个 Cron/账号
本地服务暴露到公网	无限免费	Cloudflare Tunnel 替代 ngrok

一句话看懂 Free vs Paid ($5/月)

新解锁：Containers、Email Sending、Workers Logpush
额度提升：Workers 请求 10 万/天 → 1000 万/月；单请求 CPU 10ms → 5 分钟
上限提升：Worker 数 100 → 500；Cron 5 → 250；subrequests 50 → 10,000
AI 行为变化：Workers AI 仍是 1 万 Neurons/天，但 Paid 超出后能继续用并按量付费
关键区别：Free 下超额度会报错停止、不扣钱；Paid 下超额度会自动按量计费

需要特别注意

R2 的免费额度和 Workers 计划无关。所有人都能用 10 GB 存储 + 100 万 A 类 + 1000 万 B 类操作，超出按 $0.015/GB-月、$4.50/M A 类、$0.36/M B 类算。R2 没有"停止计费"开关，是最容易意外扣费的服务。
买 $5 套餐 = 失去 Free 的自动刹车。Free 下 Workers 请求超 10 万/天会返回 1024 错误、不扣钱；Paid 下超 1000 万/月会自动按量计费。
静态资源请求永远免费无限，即使跑在 Workers Static Assets 上也不计入 Workers 请求配额。
Service Bindings 不额外计请求费。

开源项目

想自己搭网盘、图床、临时邮箱、短链或状态页，但不想从零写？这里按用途整理了一批跑在 Cloudflare 上的开源项目。

官方仓库和模板

cloudflare/templates：官方模板总库，重点看 d1-template、r2-explorer-template、durable-chat-template、llm-chat-app-template、react-router-hono-fullstack-template、saas-admin-template、workflows-starter-template、containers-template。
cloudflare/agents：官方 Agents SDK 示例。
cloudflare/vibesdk：官方 AI web app generator。
cloudflare/workers-sdk：Wrangler 所在仓库。

内容站、博客和 CMS

microfeed/microfeed：自托管轻量 CMS，用 Pages、R2、D1、Zero Trust 组织内容、媒体、RSS 和 JSON feed。
openRin/Rin：基于 Pages、Workers、D1、R2 的边缘原生博客。
SonicJs-Org/sonicjs：Edge-native Headless CMS，技术栈是 Workers、Hono、D1、R2、HTMX。

图床、网盘和 R2 文件

ling-drag0n/CloudPaste：Workers + Workflows + D1 架构，支持文件管理、文本分享、WebDAV、多存储后端和预览。
G4brym/R2-Explorer：把 R2 bucket 做成类似 Google Drive 的管理界面。
MarSeventh/CloudFlare-ImgBed：基于 Cloudflare 的文件/图床方案，支持多存储通道。

短链接

miantiao-me/Sink：100% 跑在 Cloudflare 上的短链接系统，带分析、控制台、过期、密码和安全提示页。
crazypeace/Url-Shorten-Worker：Workers + KV 的经典短链。

网站统计、监控和状态页

benvinegar/counterscale：自托管 Web Analytics，主要依赖 Workers 和 Analytics Engine。
lyc8503/UptimeFlare：Workers 驱动的 uptime monitoring 和状态页，已迁移到 D1。

Hono、API 和 SaaS Starter

honojs/hono：Workers API 生态的核心框架。
supermemoryai/cloudflare-saas-stack：把 Cloudflare D1、Pages、鉴权、样式、存储打包成可部署 SaaS 骨架。
cloudflare/templates 里的 react-router-hono-fullstack-template、saas-admin-template。

避坑指南

Workers 运行时

为什么 Worker 跑着跑着就被杀了？ Worker 跑在 V8 isolate 里，Free 每请求 CPU 10ms，Paid 默认 30 秒、可调 5 分钟。wall time 对 HTTP 请求无限制，但 Cron、Queue consumer、DO alarm 都是 15 分钟封顶。
为什么 arrayBuffer() 会让 Worker OOM？ Worker 内存 128 MB 按 isolate 分配，并发请求共享。大 body 要用流式透传，不要整个缓存进内存。
为什么日志和缓存写入偶尔丢失？ 浮动 Promise 会被静默丢弃，必须 await 或 ctx.waitUntil()。
为什么 A 用户的数据被下一个请求读到了？ Workers 会复用 isolate，模块级变量在下一个请求里还在。请求级数据走函数参数或 env 传递。

D1

为什么查询只返回一条却烧了几百万 rows_read？ D1 按扫描行数计费，不是返回行数。没有索引的 WHERE 查询会全表扫描。用 EXPLAIN QUERY PLAN 确认走的是索引。
开了读副本为什么读到旧值？ 副本复制是异步的，刚写完立刻读可能读到旧值。用 Sessions API 保证一致性。

KV

为什么 KV 写了新值，过一会儿还读到旧的？ KV 是最终一致的边缘存储，写完立刻读到新值需要强一致场景不要用 KV，考虑 D1 或 Durable Objects。
为什么高频写同一个 key 被限流了？ 同一个 key 写入限速 1 次/秒。写密集场景走 Durable Objects。

R2

文件元数据和权限该怎么存？ R2 存文件 body，元数据存 D1。R2 的 list 只能按 key 前缀翻页，不能按其他字段查询或排序。
为什么不要从 Worker 内用 REST API 调 R2？ 多了一跳认证和网络。用 R2 binding（env.MY_BUCKET.get(key)）。

Durable Objects

为什么所有请求塞进一个 DO 就成瓶颈？ 单个 DO 软上限约 1000 req/s，实际带存储写会降到 200–500 req/s。要按"协调原子"分片。
WebSocket 长连接怎么省费？ 用 Hibernation 模式，DO 空闲时可以被驱逐出内存，来消息时自动唤醒。

国内访问

Cloudflare 免费全球网络不等于中国大陆加速。大陆访问质量受运营商、线路、DNS、监管和目标服务形态影响。

先分清两件事

普通全球网络：免费也能用，国内访问"看运气"，不承诺。
China Network：企业级付费能力，国内有节点，要 ICP，要 Enterprise 套餐。

国内访问到底慢在哪

DNS 层：1.1.1.1 在国内被污染，递归 DNS 解析 Cloudflare 域名时常返回错误或劣质 IP。
路由层：电信、联通、移动到 Cloudflare 边缘节点的路径不同，高峰期丢包、绕路、TCP 重传很常见。
域名层：.workers.dev、.pages.dev、*.r2.dev 在国内经常被污染或不可达。用自己的域名几乎是硬要求。
产品层：Turnstile、Web Analytics、Workers AI 的端点在国内可用性差异很大。

橙云 vs 灰云

橙云（Proxied）：流量走 Cloudflare 全球网络，国内访问"看运气"。
灰云（DNS only）：只走 Cloudflare DNS，不进 Cloudflare 代理，可以直接指向国内源站或国内 CDN。

备案这件事

服务器在国内，必须备案。
服务器在境外（包括 Cloudflare），不需要备案，但国内访问可能不稳定。
境外注册商买的域名通常无法备案，需要把域名转入境内注册商。
未备案 ≠ 被墙。能不能访问看线路和内容，不看备案。
企业面向大陆正式运营，绕不开备案。

普通项目怎么做

用自己的域名，不要只给 workers.dev 或 pages.dev。
页面尽量静态化，减少首屏 API 依赖。
自托管所有静态资源，不要拉 Google Fonts、jsdelivr 等国内不稳的第三方 CDN。
图片压缩，静态资源文件不要过大。
给关键资源设清楚的缓存策略。
用国内外多地监控看真实可用性。
第三方 JS 做好降级。

国内测速和拨测工具

ITDOG（itdog.cn）：全国多地 HTTP / Ping / Traceroute。
17 测（17ce.com）：HTTP、Ping、路由跟踪、DNS 解析。
站长之家测速（tool.chinaz.com/speed）：全国多节点 HTTP 测速。
拨测（boce.com）：HTTP / Ping / DNS / Traceroute，按运营商细分。

方案选型

海外为主，国内少量读者：Cloudflare 免费 + 自有域名 + 页面轻量化 + 多地拨测。
国内为主，海外少量：国内云主站 + Cloudflare 做海外镜像，或用智能 DNS 按地理分流。
国内海外都重要：双轨部署，按地理 DNS 分流。
企业 + 必须国内加速 + 能备案：Cloudflare China Network（Enterprise + ICP + 单独订阅）。

官方资源

Workers Best Practices
Workers Examples
create-cloudflare
Workers Bindings
Workers Limits
Wrangler
Pages
China Network
Cloudflare Support
Log Explorer
AI Gateway
cloudflare/templates
cloudflare/agents
Cloudflare Pricing

字节笔记本

AI 编程时代的 Cloudflare 实战手册

功能模块

站点基础

计算

数据存储

AI

媒体

安全

观测

AI 编程工作流

三分钟搞定

这些东西分别是干嘛的

常见架构模式

AI 编程 Cloudflare 常见翻车点

计费与额度

先搞懂额度怎么算

免费能扛多少真实量

一句话看懂 Free vs Paid ($5/月)

需要特别注意

开源项目

官方仓库和模板

内容站、博客和 CMS

图床、网盘和 R2 文件

短链接

网站统计、监控和状态页

Hono、API 和 SaaS Starter

避坑指南

Workers 运行时

D1

KV

R2

Durable Objects

国内访问

先分清两件事

国内访问到底慢在哪

橙云 vs 灰云

备案这件事

普通项目怎么做

国内测速和拨测工具

方案选型

官方资源