Cloudflare Pages 快速上手与团队实践
整理自团队内部技术交流（主题：Cloudflare 背景、边缘部署原理与学习路径）。面向工程与内容产出同学，侧重可落地的工作流，而非平台全功能手册。文中已做脱敏处理。
1. 为什么要关注 Cloudflare
Cloudflare 早期以域名系统（Domain Name System，DNS）解析与管理起家，现已扩展为覆盖全球边缘节点的互联网基础设施平台。除传统云主机外，域名管理、边缘计算、对象存储、媒体处理、安全防护与人工智能（Artificial Intelligence，AI）接口等能力，均可在同一控制台内组合使用。
对团队而言，推荐优先了解 Cloudflare，主要基于四点：
| 维度 | 说明 |
|---|---|
| 行业共识 | Pages / Workers 与 Vercel 同属主流无服务器（Serverless）前端托管方案；文档完整，对人与 AI 智能体均友好 |
| 成本门槛 | Workers、Pages、R2、KV、D1 等均提供免费额度；小流量演示站与内部工具多数可停留在免费档（受每日 / 每月配额约束，见第 4.3 节） |
| 工程集成 | 与 GitHub、GitLab 集成；也可直接上传构建产物；推送指定分支即可触发构建与部署 |
| 智能体协同 | 提供面向 Cursor 等 Agent 工具的插件，以及 Wrangler 命令行；配置、排障与日志查询可交给智能体完成 |
交流中强调的直接动机是：当前大量工作成果（演示页、报表、讲演材料、可视化 Artifact）本身就是前端页面或静态资源。用 Pages 把成果组织成可访问的网站，比反复传压缩包或截图更利于对内对外分享，也与现有 AI 协同开发流程契合。
2. 从 DNS 到边缘代理：核心原理
2.1 DNS 仍是底座
访问网站时，浏览器将域名解析为 IP 地址。Cloudflare 的起点是代管这一解析过程。域名可购自国内或其他注册商：若需完整 Zone 能力（含根域名绑定、代理橙云等），将权威名称服务器（Name Server）指向 Cloudflare；若仅给 Pages 绑子域名，在原 DNS 服务商添加 CNAME 即可（见第 4.1 节）。
2.2 代理层带来的能力
在「仅解析到源站 IP」之上，Cloudflare 可在边缘节点增加一层反向代理（Proxy）。请求先到达边缘，再按策略转发或拦截。常见用途包括：
- 内容分发网络（Content Delivery Network，CDN）加速与缓存
- 访问控制（按地区、规则拦截异常流量）
- 安全防护（分布式拒绝服务攻击防护、机器人校验等）
- TLS 证书自动签发与续期
因此，即便不自建机房，也可在「域名 → 边缘 → 源站或边缘应用」这条链路上完成加速、防护与业务逻辑。
2.3 Pages 与 Workers 的分工
团队日常「快速上线网站」主要依赖两类能力：
| 能力 | 角色 | 典型用途 |
|---|---|---|
| Cloudflare Pages | 静态站点与前端应用托管 | 落地页、演示站、文档站、报表展示 |
| Cloudflare Workers | 边缘侧无服务器运行时 | 轻量后端接口、鉴权、分流、与存储读写 |
二者同属 Serverless 范畴：无需自行维护虚拟机、容器编排与常规运维流水线。同类产品中 Vercel 使用广泛；Cloudflare 在免费额度、边缘能力广度以及与 DNS / 安全产品的一体化上往往更省事。
Workers 可进一步对接平台存储，支撑略复杂的后端需求：
| 存储 | 定位 |
|---|---|
| R2 | 对象存储（文件、媒体等）；出站流量不计费 |
| KV | 全球键值存储，适合配置、会话与轻量状态（最终一致性，不宜当作低延迟缓存的唯一方案） |
| D1 | 基于 SQLite 的边缘关系型数据库 |
交流中提到：内部部分含数据管理的业务，正是基于 Workers + 上述存储组合搭建，而不是先租一台云服务器再搭整套中间件。
3. 推荐工作流：仓库推送即上线
3.1 最小前置条件
- 注册 Cloudflare 账号（免费即可）
- 准备一个 Git 仓库（GitHub / GitLab），或改用直接上传构建产物
- 可选：自有域名（见第 4 节）；没有自定义域名时，平台会分配
*.pages.dev（或 Workers 对应默认域名），流程仍可跑通
3.2 连接仓库后的自动化链路
在控制台创建 Workers & Pages 应用并绑定仓库后，典型链路为：
推送代码至目标分支
→ Cloudflare 感知仓库变更
→ 执行 build（安装依赖、打包）
→ 执行 deploy（发布到边缘）
→ 默认子域名或自定义域名可访问构建日志中可见初始化、拉取分支、安装依赖、打包、部署等步骤。全部通过后，开发侧日常只需关注「写代码并推送」。构建耗时随依赖与产物体积变化，简单站点常见为数十秒至数分钟，不宜默认按「半分钟」预期。
3.3 配置要点
- 构建命令与输出目录：与 Node.js / 前端工具链相关；多数由平台根据框架探测预填，也可由智能体根据项目结构生成
- 环境变量与密钥：第三方 API Key、后端连接参数等放在项目设置中管理，避免写入仓库
- 分支与子路径：可指定监听分支；单体仓库中多个子项目时，用 Root Directory / Path 指向具体子目录再构建（见第 5 节）
- 项目配置文件：仓库内常见
wrangler.toml或wrangler.jsonc，用于 Workers / Pages 相关配置；细节可交给熟悉该生态的智能体维护
3.4 命令行工具 Wrangler
Cloudflare 提供命令行工具 Wrangler，用于本地调试、配置同步、日志查看等，与控制台能力对应。在 Cursor 等环境中，智能体常会提示通过 Wrangler 排查部署失败或检查项目状态。首次使用需完成账号鉴权，此后即可在对话中直接委托「查日志」「核对某项目配置」等工作。
4. 域名、证书与免费边界
4.1 域名策略
| 做法 | 说明 |
|---|---|
| 使用平台默认域名 | 零成本验证全流程；Pages 一般为 项目名.pages.dev，适合内部分享与原型 |
| 自定义子域名 | 在原注册商添加 CNAME，指向 Pages 提供的 *.pages.dev；不必把整个域名的 Name Server 改到 Cloudflare |
| 自定义根域名（apex） | 须将该域名添加为 Cloudflare Zone，并把权威 Name Server 指向 Cloudflare，再绑定到 Pages 项目 |
| 在 Cloudflare 注册商购域 | 支付方式通常要求国际信用卡；与「用 Pages 上站」无绑定关系，可在任意注册商购域 |
自定义域名不是上线的必要条件。无自定义域名时，跳过域名绑定即可用默认地址访问。
4.2 默认附带与需自行接入的能力
部署到 Pages / Workers 后，通常自动具备：
- 默认子域名分配与 HTTPS（SSL/TLS）证书签发、续期
- 流量走 Cloudflare 边缘时的基础 DDoS 缓解与 CDN 分发
- 控制台内基础访问与性能类观测（具体指标因产品与套餐而异）
以下能力不会因「部署成功」而自动生效，需按需配置：
- Turnstile 等人机校验：须在页面嵌入组件，并在服务端校验 token（可与 Workers / Pages Functions 配合）
- 按地区拦截、复杂 WAF 规则、Bot 管理等：依赖 DNS 接入方式与套餐，需在 Zone 或相应产品中单独设置
4.3 成本预期
以下为撰写时点附近的免费档量级口径，配额会随官方调整，以 Workers 定价 与各产品 Limits 页面为准：
| 产品 | 免费档常见量级（示意） |
|---|---|
| Workers | 约 10 万次请求 / 日（Pages Functions 计入同一配额） |
| KV | 读约 10 万次 / 日，写 / 删约 1 千次 / 日，存储约 1 GB |
| D1 | 读约 500 万行 / 日，写约 10 万行 / 日，存储约 5 GB |
| R2 | 存储约 10 GB / 月，另有 Class A / B 操作次数上限 |
补充说明：
- 域名：国内注册商常见为十几元至几十元 / 年（按后缀与活动浮动），与 Cloudflare 开发者产品是否免费无关
- 纯静态 Pages、无 Functions 或极少后端调用时，免费档通常足够支撑演示与小流量站
- 付费常见触发点：Workers 请求超限、存储与读写超限、Pro / Business 等套餐能力，或购买域名本身
目标不是替代所有云主机场景，而是让「把网页成果公开可访问」在多数团队场景下接近零运维、低现金成本。
5. 单体仓库中的多站点部署
交流中针对「一个仓库里有很多子目录、是否都要塞进同一个站点」给出两种常用做法：
做法 A：按子目录分别部署
创建应用时指定 Root Directory / Path，使构建与部署仅针对该子目录。同一仓库可对应多个独立站点（例如多个落地页、多个演示项目），互不干扰。
做法 B：根目录做聚合页
在仓库根目录维护一个索引页，链到各子项目或子站点。适合作品集、内部成果墙、讲演材料总览等「一个入口、多个模块」的呈现。
关键配置通常还包括：监听分支、构建命令、输出目录、环境变量。落地页类项目常见模式是「仓库内某子目录 = 一个独立 Pages 应用」。
6. 与 AI 协同开发的配合方式
Cloudflare 文档体系完整，且已被主流编程智能体充分索引。结合团队已有的 AI 协同开发习惯，建议工作方式如下：
先建立心智模型，再交给智能体细节
人只需理解：账号 →（可选）域名 → 绑仓库 → 推送触发构建部署。具体配置项、框架探测、Wrangler 参数可由智能体生成与修改。明确部署目标
在对话中声明「本项目将部署到 Cloudflare Pages」，智能体更易产出正确的构建配置与目录结构。失败时把日志交给智能体
部署报错时，将构建日志或 Wrangler 输出贴回对话，并要求其通过 Wrangler 核对配置，通常比人工翻文档更快。成果形态优先选网页
幻灯片、报表、可视化演示等 Artifact，尽量沉淀为可部署的前端页面；推送后即可获得稳定链接，用于内部宣讲与对外交流。
注意：对外公开站点须自行评估内容敏感度与访问控制需求，避免把仅限内部的材料误挂到公开默认域名上。
7. 学习路径建议
不必先系统学习全部 Cloudflare 产品线。建议按下列顺序试一次完整闭环：
- 注册账号，进入 Workers & Pages 区域
- 用智能体生成或准备一个简单前端页面（不必手写全部细节）
- 连接 GitHub 仓库，完成一次自动构建与部署
- 用默认域名验证访问；需要自定义域名时，子域名优先走 CNAME，根域名再考虑改 Name Server
- 需要接口或轻量数据时，再了解 Workers，以及 R2 / KV / D1 的适用边界与免费配额
- 需要本地排障或批量配置时，再安装并鉴权 Wrangler
进阶方向（遇到再学即可）：复杂交互、多人在线应用、小型论坛、游戏服务端逻辑等，会更多涉及 Workers 侧 JavaScript 运行时与数据模型设计，可在具体项目中再展开交流。
8. 要点速查
| 主题 | 一句话结论 |
|---|---|
| 平台定位 | 由 DNS 发展而来的边缘基础设施；Pages / Workers 负责无服务器上站 |
| 为何适合团队 | 免费额度覆盖小流量场景、Git 驱动部署、与 Cursor 等 Agent 协作顺畅 |
| 日常动作 | 推送分支；关注构建日志与密钥配置即可 |
| 域名 | 可选；子域名可 CNAME，根域名需 Zone + Name Server |
| 多项目 | 用子路径拆多个站点，或根目录做聚合入口 |
| 后端边界 | Workers + R2 / KV / D1，覆盖轻量后端，不必先上 Docker 全集 |
| 学习目标 | 先跑通「账号 + 仓库 + 一次部署」，细节交给文档与智能体 |
