1. 先弄明白 “cloudflare-os” 到底是什么看到这个标题第一反应可能会觉得是 Cloudflare 官方发布了一个操作系统发行版。老实说我一开始也这么找过搜了半天官方仓库并没有一个叫 cloudflare-os 的 ISO 镜像文件。这个词更多是开发者社区里的一个概念昵称指的是把 Cloudflare 全家桶——Workers、Pages、R2、D1、KV、Rules——组装起来当成一套“跑在云边缘的操作系统”来用的思路。理解这个概念有个很直观的类比。传统操作系统管的是 CPU、内存、磁盘、进程、网络协议栈你写的程序运行在一台物理或虚拟机器上。而 cloudflare-os 这套思路把“机器”抽象掉了Workers 是执行进程的运行时KV 是高速缓存表D1 是关系型数据库R2 是对象存储Pages 是静态文件入口Rules 是网络安全层。整套东西分布在全球上百个边缘节点上用户访问时从最近的节点进入平台自动完成调度。也就是说你的应用不再跑在“某一台服务器”上而是跑在一张分布式的全球网络里。这篇文章不是官方文档的翻译而是我实际搭建、部署、调优之后整理的一份实操笔记。我会从最基础的账号注册和工具安装讲起到你真正把一个带域名、带数据库、带对象存储的项目跑通为止。适合三类人看第一次接触无服务器开发的纯新手、想把自己的服务从传统服务器迁到边缘平台的老手、以及只想要一个低成本个人站点的普通站长。整体篇幅不短但每一步都会给命令、给配置、给避坑说明你可以照着一步步来。顺便提一个安全边界问题。既然聊到 Cloudflare很多人下意识想到各类网络代理工具但本文完全不涉及那些内容我们只讨论官方提供的开发者服务Workers 边缘函数、Pages 静态托管、R2 存储、D1 数据库以及相关的配置和调优。这些是正规的开发者服务用来部署应用和网站跟其他任何灰色用法没有关系。2. 核心思路拆解为什么值得把 Cloudflare 工具链组装成“操作系统”来用这套思路跟传统服务器到底差在哪得先从部署模型说起。传统方式下你要自己处理的事情很多选机房、装系统、调内核参数、配防火墙、做负载均衡、搞监控告警、处理半夜磁盘满的问题。而在 cloudflare-os 的模型里绝大多数底层问题被平台接管了。你的代码推上去后平台会把它分发到所有边缘节点任何地方的请求都从最近的节点响应。流量高峰时平台自动扩容节点故障时自动切换你唯一要关注的就是业务代码本身。这种模式最吸引人的地方我总结成三个字不关心。不需要关心实例数量因为计费按请求次数走平台自动伸缩不需要关心机房故障因为节点是复数分布的不需要关心代码部署在哪台物理机器上因为推送代码之后平台负责分发。这解放了大量运维精力尤其适合个人开发者和小团队。用生活化方式打个比方。传统部署像自己开一家面馆租门面、买灶台、请厨师生意清淡时一堆设备闲置排队爆满时又接待不过来。而 cloudflare-os 更像加入了一个成熟的连锁中央厨房你只要把菜谱代码提交给总部总部会把菜谱发给所有门店不管哪个门店接到订单都能照着菜谱快速出菜。每个门店还有一些本地备好的半成品边缘缓存所以出餐速度特别快。但选择这套方案前有三个问题必须想清楚。第一是延迟敏感度如果你的用户集中在国内某个区域传统服务器或许更经济如果用户分布在全球边缘节点优势就很明显。第二是状态管理Workers 默认是无状态的遇到长连接、WebSocket、有状态会话这类场景需要额外引入 KV、D1 或外部中间件做持久化设计。第三是平台依赖一旦业务深度绑定 Cloudflare你的部署流程、数据格式、域名解析都会围绕它转将来想迁移成本是真实存在的。2.1 动手之前先画一张“系统架构图”我强烈建议别急着敲命令先拿一张纸画出你的应用由哪些模块组成。举个典型例子一个带用户上传功能的博客站点。Pages 负责托管 HTML、CSS、JS 这些静态资源Workers 负责跑动态接口比如文章列表的 APIKV 用来存阅读量和会话状态R2 用来存用户上传的图片附件D1 存文章的标题、正文、标签这些结构化数据。把这些画成一张数据流向图每个模块之间谁调谁一目了然。后面配置绑定关系时你就不容易把存储桶和数据库的 binding 搞混。2.2 把各模块按“操作系统角色”对号入座我习惯用操作系统的视角来记忆 Cloudflare 服务的定位。Workers 是 CPU负责执行逻辑KV 是缓存层适合高并发读D1 是数据库对应持久化存储R2 是磁盘阵列适合文件对象Pages 是文件系统入口提供静态资源访问Rules 和防火墙类比成安全模块负责流量过滤。记忆归记忆真实选型还是要看场景。比如用户头像这种图片文件就该放 R2因为它自带了边缘缓存全球读取都快登录会话这种短时效的数据放 KV 正合适需要按条件查询的结构化数据就必须上 D1别硬塞进 KV。3. 动手实操从零开始搭建一套“cloudflare-os”开发环境理解了概念之后真正的硬功夫在于实操。下面按我的操作顺序完整走一遍你跟着做就能跑通一个包含前端、后端 API、数据库和对象存储的完整项目。3.1 准备工具链注册账号、安装 Node.js 与 Wrangler第一步是注册一个 Cloudflare 账号直接在官网注册即可免费套餐就够大部分个人项目使用了。注册时建议开启两步验证毕竟后面你要在上面绑定域名和存储数据安全级别不能太低。第二步是准备本地开发环境。Wrangler 是官方命令行工具用来创建、调试、部署 Workers 和 Pages 项目。它依赖 Node.js所以先去官网安装 LTS 版本的 Node.js装完在终端验证一下版本node -v npm -v都正常输出版本号之后全局安装 Wranglernpm install -g wrangler安装完成后检查版本wrangler --version首次使用需要登录授权wrangler login这条命令会拉起浏览器你登录刚才注册的账号并确认授权即可。这里说一个我踩过的坑如果你用的是公司电脑网络策略比较严格login 时浏览器可能打不开授权页。替代方案是使用 API Token在 Cloudflare 控制台创建 Token然后通过CLOUDFLARE_API_TOKEN环境变量让 Wrangler 读取。具体方法后面遇到时再展开。3.2 初始化第一个 Worker 项目并本地联调登录成功后创建一个新项目目录并初始化mkdir my-cloudflare-os cd my-cloudflare-os wrangler init my-worker初始化过程会问你是否使用 TypeScript。如果是小项目JavaScript 就够了选 No如果你对类型检查有需求选 Yes 我也没有意见只是后面代码示例我会用 JavaScript 写。初始化完成后项目里会出现一个src/index.js里面有一个 Entry Point 函数export default { async fetch(request, env, ctx) { return new Response(Hello Cloudflare OS!); } };这个fetch函数就是整个 Worker 的核心入口平台收到 HTTP 请求后会调用它。你可以把request当成请求对象的封装env里装着你在配置里绑定的各类资源引用ctx提供一些后台任务接口。本地运行的命令非常直观wrangler dev它会启动一个本地调试服务器默认监听http://localhost:8787你可以在浏览器直接访问。每次修改代码它都会自动热更新体验跟本地开发普通 Node 服务差不多。这能让你在正式部署之前把业务逻辑完整调通省下不少线上调试的成本。我实际测试下来有一个细节值得注意本地wrangler dev默认不会执行边缘缓存逻辑也就是说caches.default这类 API 的表现跟线上会有差异。如果你依赖边缘缓存建议尽早部署到预览环境用真实域名测试不要等到全部写完才发现行为不一致。3.3 用 Pages 托管前端并绑定自定义域名接下来把前端部分接进来。Pages 是 Cloudflare 的静态站点托管服务支持直接连接 Git 仓库自动构建也支持命令行手动上传构建产物。我更推荐 Git 集成的方式因为以后每次 push 代码它会自动重新构建发布省心很多。先在项目根目录准备前端构建产物。假设你用 Vue 或 React执行构建之后会生成一个dist目录。然后你可以在 Cloudflare 控制台里进入 Pages选择“创建项目”连接你的 Git 仓库把构建命令和输出目录配置好例如构建命令填npm run build输出目录填dist。第一次构建会自动触发完成后你会得到一个形如xxx.pages.dev的默认域名可以直接预览。绑定自定义域名也很简单。进入项目的“自定义域”菜单输入你想要的子域名比如blog.yourdomain.com。Cloudflare 会自动检测你的域名 DNS 托管状态如果域名已经托管在 Cloudflare它会自动添加 CNAME 记录如果还没有托管则需要在你的 DNS 服务商那边手动添加。整个过程都是可视化操作不需要翻配置文件。这里有一个很容易忽略的点Pages 不仅是静态托管它还可以挂载 Functions。你在项目里创建一个functions目录里面放api/hello.js部署后就会得到/api/hello这个动态接口逻辑会被当作 Worker 执行。这样前端和动态接口在同一个仓库里部署时一次完成不用分别管理两个项目。对于个人站点来说这个模式非常省事。3.4 接入 R2 对象存储与 D1 数据库让数据真正跑通一个连数据库和存储都没有的网站只能算静态站。要把数据层接进来需要创建 R2 存储桶和 D1 数据库然后在 Wrangler 配置里绑定它们。在控制台进入 R2创建一个存储桶名字可以叫my-media。同样进入 D1创建一个数据库记下它的 database ID。然后在项目根目录的wrangler.toml文件里加上绑定配置name my-worker main src/index.js [[r2_buckets]] binding BUCKET bucket_name my-media [[d1_databases]] binding DB database_name my-db database_id 你的数据库ID修改完配置记得重启wrangler dev这样本地环境才会加载新的 binding。然后修改 Worker 代码让数据真正用起来export default { async fetch(request, env, ctx) { if (request.url.endsWith(/upload)) { await env.BUCKET.put(demo.txt, hello r2); return new Response(uploaded); } if (request.url.endsWith(/query)) { const result await env.DB.prepare(SELECT 1 AS number).first(); return new Response(d1 number: ${result.number}); } return new Response(ok); } };部署上线wrangler deploy部署完成后你访问线上的your-worker.workers.dev/upload它会在 R2 里创建demo.txt访问/query它会执行一条 D1 查询。到这里一个“前端 Pages 动态 Worker 对象存储 R2 数据库 D1”的完整闭环已经打通了。这个结构就是你自己的 cloudflare-os 最小可用版本。4. 关键参数选型与性能调优实录跑通只是第一步接下来是让它跑得稳、跑得快。这一部分很多人直接跳过结果上线后遇到超时、缓存不生效、流量费超预期等问题才回头补功课。我把实际调优过的参数和选型逻辑整理出来给你做个参考。4.1 Worker 的运行时配额怎么选Worker 的运行时配额包括每请求的 CPU 时间、内存限制和请求体大小限制。这些参数在控制台的 Worker 配置页面里可以设置。CPU 时间配额尤其关键它决定了单个请求最多能消耗多少计算资源。如果你跑正则匹配、图片处理或者复杂 JSON 解析很容易达到上限。我的习惯是普通 API 路由把 CPU 时间配额设到中小档位就行够用且能降低成本但如果你在里面做了图片缩略图、SSR 渲染这类重活就得预留更大余量。内存限制同理记住你在 Worker 里不能像在 Node 服务里那样随意使用大内存数组。另一个常见坑是外部请求的响应时间Worker 对同步 fetch 外部接口有超时限制。调外部接口时务必在代码里自己设置超时和熔断避免上游接口变慢导致整个请求被拖死。4.2 缓存策略与 KV 的 TTL 设置缓存是这套架构的灵魂。没有缓存的话每个请求都会穿透到源站浪费边缘节点的优势。我一般在代码里设置两层缓存一层是 HTTP 层的 Cache-Control另一层是 KV 的 TTL。HTTP 层缓存作用于响应体就是给 Response 添加Cache-Control头。静态资源可以设置public, max-age86400让 CDN 缓存一天动态接口则按业务场景比如文章详情页可以设置s-maxage300只让边缘节点缓存 5 分钟浏览器不缓存。这里s-maxage是关键它专门控制 CDN 中间缓存的时效而max-age控制浏览器缓存。两者要区分清楚别混着写。KV 的 TTL 则是针对键值对的。写入 KV 时可以指定过期时间例如把热门文章的 JSON 数据写入 KV并设置 TTL 为 600 秒。过期后系统自动清除下次请求会回源计算再重新写入。这样能有效减少回源次数代价是有最多 10 分钟的数据延迟。像文章列表这种对实时性要求不高的数据完全可以接受。如果要求实时比如用户余额那就不建议用 KV 缓存了直接查 D1。4.3 路由与域名绑定的细节路由配置也是容易出问题的一块。你可以在 Worker 的wrangler.toml里配置路由规则例如routes [ { pattern blog.yourdomain.com/api/*, zone_name yourdomain.com } ]这样只有blog.yourdomain.com/api/下的请求才会进入这个 Worker其他路径走 Pages 静态页面。用路由粒度把不同业务拆到不同 Worker 里是保持项目清爽的关键。我见过有人把所有逻辑塞进一个 Worker结果代码几千行构建慢、排查难。正确做法是静态资源走 Pages文章 API 走一个 Worker上传接口走另一个 Worker互不干扰也方便单独部署和回滚。关于域名绑定还有一个细节如果你用 pages.dev 或者 workers.dev 的默认域名开发测试没问题但生产环境强烈建议绑定自己的域名。自定义域名下你可以用边缘证书管理功能申请 HTTPS 证书自动续期不用自己折腾证书文件。5. 踩坑实录开发中遇到的常见问题与排查方法这部分是我最想写的内容。因为网上教程大多讲怎么创建和部署但实际开发中真正磨人的是那些官方文档里一笔带过、等你自己踩到了才明白的问题。我把自己遇到过的典型问题整理成了一份速查录。5.1 冷启动和首次访问慢的问题无服务器环境有个绕不开的痛点冷启动。也就是一个 Worker 实例在空闲一段时间后处理下一个请求前需要重新初始化。实际表现是第一次访问时延迟可能到几百毫秒甚至几秒但后续请求就恢复几十毫秒的水平。我的应对方式分三层。第一层给关键接口开启预热的健康检查让它每隔一段时间自动发一个请求进来保持实例活跃。第二层引入 KV 缓存虽然冷启动依然存在但至少缓存命中时响应很快用户感知不到明显延迟。第三层重要页面提前写死一部分静态内容或者用 Pages 的 Static Assets 托管首屏动态部分再异步加载。这样首屏始终是静态的快得很动态数据渐进补充。5.2 环境变量、Secret 与敏感信息泄漏云函数最容易犯的错误就是硬编码密钥在代码里。比如调用第三方 API 时直接写const token sk-xxxx。一旦代码推送到 Git 仓库密钥就彻底暴露了。正确做法是把密钥放到 Worker 设置的“变量和机密”里。明文变量适合一般配置机密项则用来保存 API Key。设置好后代码里通过env.API_TOKEN读取。注意控制台里机密一旦创建就不能再查看明文只能覆盖更新。这确保了运行平台之外的可见性最低。还有一个容易忽略的安全细节点外部调用内部资源的身份验证。很多人以为 Worker 地址不外传就安全实际上服务地址只要被扫到就能访问。至少要在请求头里检查一个自定义的 Token或者直接使用 Cloudflare 的 Access 服务做身份校验别把内部接口裸奔在网上。5.3 免费配额超额之后发生了什么免费额度的具体数值会随时间调整以官方文档为准但超额后会发生什么我亲测过这里讲一下现象。Workers 免费套餐按天计算请求数超出后接口不会立刻中断而是开始明显变慢或者直接返回 429 状态码提示请求量超限。Pages 的免费套餐主要限制构建次数一个自然周内构建用完后Git push 不会触发自动部署但你仍可以手动部署。D1 免费套餐则对读、写操作次数有限制数据量本身也有容量上限。R2 免费套餐主要限制存储容量和 A 类、B 类操作数量。A 类操作指写入B 类操作指读取。如果你大量调用 R2 写接口A 类很快会用完而前几年很多统计口径是只按存储量计费的现在按操作次数收费后行为差异很大。建议上线前给自己写一个简单的配额监控脚本每天跑一次把当前用量推送到自己的 API 里存档做到心中有数。5.4 常见问题速查表问题现象根本原因解决方案本地测试通过线上数据不对binding 配置未更新或环境变量缺失检查 wrangler.toml 绑定配置确认线上 Secrets 已设置首次访问非常慢冷启动增加预热请求或对首屏做静态化处理接口返回 429免费配额超限查看配额用量升级套餐或优化请求次数缓存内容一直不更新Cache-Control 设置太长调整 s-maxage 或主动触发缓存清除fetch 外部接口超时上游响应慢没有超时熔断代码里给 fetch 加 AbortController 超时控制密钥泄露在代码仓库硬编码 Secrets立刻轮换密钥改用 env 读取并清理 Git 历史这个表格看起来很基础但每一条背后都是一次真实的线上事故。尤其是缓存不更新我在调试时曾经反复改代码、重新部署页面就是不变最后才发现是 CDN 缓存了旧响应。所以遇到“代码改了没生效”的问题第一步不是看代码而是先排除边缘缓存。6. 把“cloudflare-os”真正用起来之后的几点体会整个项目从零搭建到稳定运行之后我最大的感受是运维负担真的降下来了。以前跑一个带数据库和存储的项目我得操心服务器续费、系统安全补丁、磁盘空间清理半夜收到告警还要爬起来看日志。现在这套基于边缘的架构绝大部分底层问题都由平台兜底了我只需要专注写业务代码和关注配额用量。第二个感受是调试方式变了。传统服务器可以 SSH 上去抓日志、临时跑脚本在边缘环境里没法这么做。你必须把可观测性前置从设计阶段就想好日志输出和错误追踪怎么做。我的项目里给每个 Worker 都加了结构化的 JSON 日志配合抓取诊断服务出问题时按 trace ID 定位效率反而比在服务器上翻 syslog 高。第三个感受是从成本角度看非常划算。个人项目在免费额度内就能长时间跑着几乎不用投入服务器费用。即便流量涨到需要付费Workers 按量计费的粒度也比整租服务器灵活费用随流量变化不会出现一台服务器利用率只有个位数还在买的情况。我建议每个想折腾个人项目的人都试着用这套思路重组一下自己的应用哪怕只是把一个工具站或者 API 服务搬上去体验一次“把操作系统装在全球网络里”的感觉。最后分享一个小技巧把 Wrangler 的部署命令写进 npm scripts再接上 Git 的 pre-push 钩子每次 push 前自动跑测试和构建构建通过后自动部署。这样整个“code - test - build - deploy”链路完全自动化速度只有几秒钟。对于一个个人项目来说这已经是相当顺手的工作流了。 
长河君 · 2026/10/28 7:08:46 · 阅读 1.2k Cloudflare Workers实战：搭建属于你的边缘计算操作系统
1. 先弄明白 “cloudflare-os” 到底是什么看到这个标题第一反应可能会觉得是 Cloudflare 官方发布了一个操作系统发行版。老实说我一开始也这么找过搜了半天官方仓库并没有一个叫 cloudflare-os 的 ISO 镜像文件。这个词更多是开发者社区里的一个概念昵称指的是把 Cloudflare 全家桶——Workers、Pages、R2、D1、KV、Rules——组装起来当成一套“跑在云边缘的操作系统”来用的思路。理解这个概念有个很直观的类比。传统操作系统管的是 CPU、内存、磁盘、进程、网络协议栈你写的程序运行在一台物理或虚拟机器上。而 cloudflare-os 这套思路把“机器”抽象掉了Workers 是执行进程的运行时KV 是高速缓存表D1 是关系型数据库R2 是对象存储Pages 是静态文件入口Rules 是网络安全层。整套东西分布在全球上百个边缘节点上用户访问时从最近的节点进入平台自动完成调度。也就是说你的应用不再跑在“某一台服务器”上而是跑在一张分布式的全球网络里。这篇文章不是官方文档的翻译而是我实际搭建、部署、调优之后整理的一份实操笔记。我会从最基础的账号注册和工具安装讲起到你真正把一个带域名、带数据库、带对象存储的项目跑通为止。适合三类人看第一次接触无服务器开发的纯新手、想把自己的服务从传统服务器迁到边缘平台的老手、以及只想要一个低成本个人站点的普通站长。整体篇幅不短但每一步都会给命令、给配置、给避坑说明你可以照着一步步来。顺便提一个安全边界问题。既然聊到 Cloudflare很多人下意识想到各类网络代理工具但本文完全不涉及那些内容我们只讨论官方提供的开发者服务Workers 边缘函数、Pages 静态托管、R2 存储、D1 数据库以及相关的配置和调优。这些是正规的开发者服务用来部署应用和网站跟其他任何灰色用法没有关系。2. 核心思路拆解为什么值得把 Cloudflare 工具链组装成“操作系统”来用这套思路跟传统服务器到底差在哪得先从部署模型说起。传统方式下你要自己处理的事情很多选机房、装系统、调内核参数、配防火墙、做负载均衡、搞监控告警、处理半夜磁盘满的问题。而在 cloudflare-os 的模型里绝大多数底层问题被平台接管了。你的代码推上去后平台会把它分发到所有边缘节点任何地方的请求都从最近的节点响应。流量高峰时平台自动扩容节点故障时自动切换你唯一要关注的就是业务代码本身。这种模式最吸引人的地方我总结成三个字不关心。不需要关心实例数量因为计费按请求次数走平台自动伸缩不需要关心机房故障因为节点是复数分布的不需要关心代码部署在哪台物理机器上因为推送代码之后平台负责分发。这解放了大量运维精力尤其适合个人开发者和小团队。用生活化方式打个比方。传统部署像自己开一家面馆租门面、买灶台、请厨师生意清淡时一堆设备闲置排队爆满时又接待不过来。而 cloudflare-os 更像加入了一个成熟的连锁中央厨房你只要把菜谱代码提交给总部总部会把菜谱发给所有门店不管哪个门店接到订单都能照着菜谱快速出菜。每个门店还有一些本地备好的半成品边缘缓存所以出餐速度特别快。但选择这套方案前有三个问题必须想清楚。第一是延迟敏感度如果你的用户集中在国内某个区域传统服务器或许更经济如果用户分布在全球边缘节点优势就很明显。第二是状态管理Workers 默认是无状态的遇到长连接、WebSocket、有状态会话这类场景需要额外引入 KV、D1 或外部中间件做持久化设计。第三是平台依赖一旦业务深度绑定 Cloudflare你的部署流程、数据格式、域名解析都会围绕它转将来想迁移成本是真实存在的。2.1 动手之前先画一张“系统架构图”我强烈建议别急着敲命令先拿一张纸画出你的应用由哪些模块组成。举个典型例子一个带用户上传功能的博客站点。Pages 负责托管 HTML、CSS、JS 这些静态资源Workers 负责跑动态接口比如文章列表的 APIKV 用来存阅读量和会话状态R2 用来存用户上传的图片附件D1 存文章的标题、正文、标签这些结构化数据。把这些画成一张数据流向图每个模块之间谁调谁一目了然。后面配置绑定关系时你就不容易把存储桶和数据库的 binding 搞混。2.2 把各模块按“操作系统角色”对号入座我习惯用操作系统的视角来记忆 Cloudflare 服务的定位。Workers 是 CPU负责执行逻辑KV 是缓存层适合高并发读D1 是数据库对应持久化存储R2 是磁盘阵列适合文件对象Pages 是文件系统入口提供静态资源访问Rules 和防火墙类比成安全模块负责流量过滤。记忆归记忆真实选型还是要看场景。比如用户头像这种图片文件就该放 R2因为它自带了边缘缓存全球读取都快登录会话这种短时效的数据放 KV 正合适需要按条件查询的结构化数据就必须上 D1别硬塞进 KV。3. 动手实操从零开始搭建一套“cloudflare-os”开发环境理解了概念之后真正的硬功夫在于实操。下面按我的操作顺序完整走一遍你跟着做就能跑通一个包含前端、后端 API、数据库和对象存储的完整项目。3.1 准备工具链注册账号、安装 Node.js 与 Wrangler第一步是注册一个 Cloudflare 账号直接在官网注册即可免费套餐就够大部分个人项目使用了。注册时建议开启两步验证毕竟后面你要在上面绑定域名和存储数据安全级别不能太低。第二步是准备本地开发环境。Wrangler 是官方命令行工具用来创建、调试、部署 Workers 和 Pages 项目。它依赖 Node.js所以先去官网安装 LTS 版本的 Node.js装完在终端验证一下版本node -v npm -v都正常输出版本号之后全局安装 Wranglernpm install -g wrangler安装完成后检查版本wrangler --version首次使用需要登录授权wrangler login这条命令会拉起浏览器你登录刚才注册的账号并确认授权即可。这里说一个我踩过的坑如果你用的是公司电脑网络策略比较严格login 时浏览器可能打不开授权页。替代方案是使用 API Token在 Cloudflare 控制台创建 Token然后通过CLOUDFLARE_API_TOKEN环境变量让 Wrangler 读取。具体方法后面遇到时再展开。3.2 初始化第一个 Worker 项目并本地联调登录成功后创建一个新项目目录并初始化mkdir my-cloudflare-os cd my-cloudflare-os wrangler init my-worker初始化过程会问你是否使用 TypeScript。如果是小项目JavaScript 就够了选 No如果你对类型检查有需求选 Yes 我也没有意见只是后面代码示例我会用 JavaScript 写。初始化完成后项目里会出现一个src/index.js里面有一个 Entry Point 函数export default { async fetch(request, env, ctx) { return new Response(Hello Cloudflare OS!); } };这个fetch函数就是整个 Worker 的核心入口平台收到 HTTP 请求后会调用它。你可以把request当成请求对象的封装env里装着你在配置里绑定的各类资源引用ctx提供一些后台任务接口。本地运行的命令非常直观wrangler dev它会启动一个本地调试服务器默认监听http://localhost:8787你可以在浏览器直接访问。每次修改代码它都会自动热更新体验跟本地开发普通 Node 服务差不多。这能让你在正式部署之前把业务逻辑完整调通省下不少线上调试的成本。我实际测试下来有一个细节值得注意本地wrangler dev默认不会执行边缘缓存逻辑也就是说caches.default这类 API 的表现跟线上会有差异。如果你依赖边缘缓存建议尽早部署到预览环境用真实域名测试不要等到全部写完才发现行为不一致。3.3 用 Pages 托管前端并绑定自定义域名接下来把前端部分接进来。Pages 是 Cloudflare 的静态站点托管服务支持直接连接 Git 仓库自动构建也支持命令行手动上传构建产物。我更推荐 Git 集成的方式因为以后每次 push 代码它会自动重新构建发布省心很多。先在项目根目录准备前端构建产物。假设你用 Vue 或 React执行构建之后会生成一个dist目录。然后你可以在 Cloudflare 控制台里进入 Pages选择“创建项目”连接你的 Git 仓库把构建命令和输出目录配置好例如构建命令填npm run build输出目录填dist。第一次构建会自动触发完成后你会得到一个形如xxx.pages.dev的默认域名可以直接预览。绑定自定义域名也很简单。进入项目的“自定义域”菜单输入你想要的子域名比如blog.yourdomain.com。Cloudflare 会自动检测你的域名 DNS 托管状态如果域名已经托管在 Cloudflare它会自动添加 CNAME 记录如果还没有托管则需要在你的 DNS 服务商那边手动添加。整个过程都是可视化操作不需要翻配置文件。这里有一个很容易忽略的点Pages 不仅是静态托管它还可以挂载 Functions。你在项目里创建一个functions目录里面放api/hello.js部署后就会得到/api/hello这个动态接口逻辑会被当作 Worker 执行。这样前端和动态接口在同一个仓库里部署时一次完成不用分别管理两个项目。对于个人站点来说这个模式非常省事。3.4 接入 R2 对象存储与 D1 数据库让数据真正跑通一个连数据库和存储都没有的网站只能算静态站。要把数据层接进来需要创建 R2 存储桶和 D1 数据库然后在 Wrangler 配置里绑定它们。在控制台进入 R2创建一个存储桶名字可以叫my-media。同样进入 D1创建一个数据库记下它的 database ID。然后在项目根目录的wrangler.toml文件里加上绑定配置name my-worker main src/index.js [[r2_buckets]] binding BUCKET bucket_name my-media [[d1_databases]] binding DB database_name my-db database_id 你的数据库ID修改完配置记得重启wrangler dev这样本地环境才会加载新的 binding。然后修改 Worker 代码让数据真正用起来export default { async fetch(request, env, ctx) { if (request.url.endsWith(/upload)) { await env.BUCKET.put(demo.txt, hello r2); return new Response(uploaded); } if (request.url.endsWith(/query)) { const result await env.DB.prepare(SELECT 1 AS number).first(); return new Response(d1 number: ${result.number}); } return new Response(ok); } };部署上线wrangler deploy部署完成后你访问线上的your-worker.workers.dev/upload它会在 R2 里创建demo.txt访问/query它会执行一条 D1 查询。到这里一个“前端 Pages 动态 Worker 对象存储 R2 数据库 D1”的完整闭环已经打通了。这个结构就是你自己的 cloudflare-os 最小可用版本。4. 关键参数选型与性能调优实录跑通只是第一步接下来是让它跑得稳、跑得快。这一部分很多人直接跳过结果上线后遇到超时、缓存不生效、流量费超预期等问题才回头补功课。我把实际调优过的参数和选型逻辑整理出来给你做个参考。4.1 Worker 的运行时配额怎么选Worker 的运行时配额包括每请求的 CPU 时间、内存限制和请求体大小限制。这些参数在控制台的 Worker 配置页面里可以设置。CPU 时间配额尤其关键它决定了单个请求最多能消耗多少计算资源。如果你跑正则匹配、图片处理或者复杂 JSON 解析很容易达到上限。我的习惯是普通 API 路由把 CPU 时间配额设到中小档位就行够用且能降低成本但如果你在里面做了图片缩略图、SSR 渲染这类重活就得预留更大余量。内存限制同理记住你在 Worker 里不能像在 Node 服务里那样随意使用大内存数组。另一个常见坑是外部请求的响应时间Worker 对同步 fetch 外部接口有超时限制。调外部接口时务必在代码里自己设置超时和熔断避免上游接口变慢导致整个请求被拖死。4.2 缓存策略与 KV 的 TTL 设置缓存是这套架构的灵魂。没有缓存的话每个请求都会穿透到源站浪费边缘节点的优势。我一般在代码里设置两层缓存一层是 HTTP 层的 Cache-Control另一层是 KV 的 TTL。HTTP 层缓存作用于响应体就是给 Response 添加Cache-Control头。静态资源可以设置public, max-age86400让 CDN 缓存一天动态接口则按业务场景比如文章详情页可以设置s-maxage300只让边缘节点缓存 5 分钟浏览器不缓存。这里s-maxage是关键它专门控制 CDN 中间缓存的时效而max-age控制浏览器缓存。两者要区分清楚别混着写。KV 的 TTL 则是针对键值对的。写入 KV 时可以指定过期时间例如把热门文章的 JSON 数据写入 KV并设置 TTL 为 600 秒。过期后系统自动清除下次请求会回源计算再重新写入。这样能有效减少回源次数代价是有最多 10 分钟的数据延迟。像文章列表这种对实时性要求不高的数据完全可以接受。如果要求实时比如用户余额那就不建议用 KV 缓存了直接查 D1。4.3 路由与域名绑定的细节路由配置也是容易出问题的一块。你可以在 Worker 的wrangler.toml里配置路由规则例如routes [ { pattern blog.yourdomain.com/api/*, zone_name yourdomain.com } ]这样只有blog.yourdomain.com/api/下的请求才会进入这个 Worker其他路径走 Pages 静态页面。用路由粒度把不同业务拆到不同 Worker 里是保持项目清爽的关键。我见过有人把所有逻辑塞进一个 Worker结果代码几千行构建慢、排查难。正确做法是静态资源走 Pages文章 API 走一个 Worker上传接口走另一个 Worker互不干扰也方便单独部署和回滚。关于域名绑定还有一个细节如果你用 pages.dev 或者 workers.dev 的默认域名开发测试没问题但生产环境强烈建议绑定自己的域名。自定义域名下你可以用边缘证书管理功能申请 HTTPS 证书自动续期不用自己折腾证书文件。5. 踩坑实录开发中遇到的常见问题与排查方法这部分是我最想写的内容。因为网上教程大多讲怎么创建和部署但实际开发中真正磨人的是那些官方文档里一笔带过、等你自己踩到了才明白的问题。我把自己遇到过的典型问题整理成了一份速查录。5.1 冷启动和首次访问慢的问题无服务器环境有个绕不开的痛点冷启动。也就是一个 Worker 实例在空闲一段时间后处理下一个请求前需要重新初始化。实际表现是第一次访问时延迟可能到几百毫秒甚至几秒但后续请求就恢复几十毫秒的水平。我的应对方式分三层。第一层给关键接口开启预热的健康检查让它每隔一段时间自动发一个请求进来保持实例活跃。第二层引入 KV 缓存虽然冷启动依然存在但至少缓存命中时响应很快用户感知不到明显延迟。第三层重要页面提前写死一部分静态内容或者用 Pages 的 Static Assets 托管首屏动态部分再异步加载。这样首屏始终是静态的快得很动态数据渐进补充。5.2 环境变量、Secret 与敏感信息泄漏云函数最容易犯的错误就是硬编码密钥在代码里。比如调用第三方 API 时直接写const token sk-xxxx。一旦代码推送到 Git 仓库密钥就彻底暴露了。正确做法是把密钥放到 Worker 设置的“变量和机密”里。明文变量适合一般配置机密项则用来保存 API Key。设置好后代码里通过env.API_TOKEN读取。注意控制台里机密一旦创建就不能再查看明文只能覆盖更新。这确保了运行平台之外的可见性最低。还有一个容易忽略的安全细节点外部调用内部资源的身份验证。很多人以为 Worker 地址不外传就安全实际上服务地址只要被扫到就能访问。至少要在请求头里检查一个自定义的 Token或者直接使用 Cloudflare 的 Access 服务做身份校验别把内部接口裸奔在网上。5.3 免费配额超额之后发生了什么免费额度的具体数值会随时间调整以官方文档为准但超额后会发生什么我亲测过这里讲一下现象。Workers 免费套餐按天计算请求数超出后接口不会立刻中断而是开始明显变慢或者直接返回 429 状态码提示请求量超限。Pages 的免费套餐主要限制构建次数一个自然周内构建用完后Git push 不会触发自动部署但你仍可以手动部署。D1 免费套餐则对读、写操作次数有限制数据量本身也有容量上限。R2 免费套餐主要限制存储容量和 A 类、B 类操作数量。A 类操作指写入B 类操作指读取。如果你大量调用 R2 写接口A 类很快会用完而前几年很多统计口径是只按存储量计费的现在按操作次数收费后行为差异很大。建议上线前给自己写一个简单的配额监控脚本每天跑一次把当前用量推送到自己的 API 里存档做到心中有数。5.4 常见问题速查表问题现象根本原因解决方案本地测试通过线上数据不对binding 配置未更新或环境变量缺失检查 wrangler.toml 绑定配置确认线上 Secrets 已设置首次访问非常慢冷启动增加预热请求或对首屏做静态化处理接口返回 429免费配额超限查看配额用量升级套餐或优化请求次数缓存内容一直不更新Cache-Control 设置太长调整 s-maxage 或主动触发缓存清除fetch 外部接口超时上游响应慢没有超时熔断代码里给 fetch 加 AbortController 超时控制密钥泄露在代码仓库硬编码 Secrets立刻轮换密钥改用 env 读取并清理 Git 历史这个表格看起来很基础但每一条背后都是一次真实的线上事故。尤其是缓存不更新我在调试时曾经反复改代码、重新部署页面就是不变最后才发现是 CDN 缓存了旧响应。所以遇到“代码改了没生效”的问题第一步不是看代码而是先排除边缘缓存。6. 把“cloudflare-os”真正用起来之后的几点体会整个项目从零搭建到稳定运行之后我最大的感受是运维负担真的降下来了。以前跑一个带数据库和存储的项目我得操心服务器续费、系统安全补丁、磁盘空间清理半夜收到告警还要爬起来看日志。现在这套基于边缘的架构绝大部分底层问题都由平台兜底了我只需要专注写业务代码和关注配额用量。第二个感受是调试方式变了。传统服务器可以 SSH 上去抓日志、临时跑脚本在边缘环境里没法这么做。你必须把可观测性前置从设计阶段就想好日志输出和错误追踪怎么做。我的项目里给每个 Worker 都加了结构化的 JSON 日志配合抓取诊断服务出问题时按 trace ID 定位效率反而比在服务器上翻 syslog 高。第三个感受是从成本角度看非常划算。个人项目在免费额度内就能长时间跑着几乎不用投入服务器费用。即便流量涨到需要付费Workers 按量计费的粒度也比整租服务器灵活费用随流量变化不会出现一台服务器利用率只有个位数还在买的情况。我建议每个想折腾个人项目的人都试着用这套思路重组一下自己的应用哪怕只是把一个工具站或者 API 服务搬上去体验一次“把操作系统装在全球网络里”的感觉。最后分享一个小技巧把 Wrangler 的部署命令写进 npm scripts再接上 Git 的 pre-push 钩子每次 push 前自动跑测试和构建构建通过后自动部署。这样整个“code - test - build - deploy”链路完全自动化速度只有几秒钟。对于一个个人项目来说这已经是相当顺手的工作流了。