Cloudflare cf CLI 与静态 Pages 部署

背景

维护个人技术站时，最稳妥的一类形态是 纯静态：Markdown 或模板在本地（或 CI）生成 HTML/CSS/JS，再推到 CDN 边缘。Cloudflare Pages 提供免费额度的静态托管与自定义域名；配套的开发者 CLI / API 则用来上传产物、查看部署状态。

0xKEV 本身就是这条路径：仓库里构建出整站文件树，再 Direct Upload 到 Pages 项目 0xkev，域名挂在 0xkev.neonriftlab.com。这和「在 Cloudflare 上跑 Agent / Workers 业务逻辑」是不同层——静态知识站不必绑定 Agent 运行时。

要点

1. 产物与源码分离：源稿在 0xkev-docs-src/，构建脚本写出站点根目录；上传的是构建结果，不是未编译的草稿。
2. Direct Upload：通过上传令牌把文件哈希清单挂到 production；已存在的哈希可跳过，缩短发版时间。
3. 缓存与版本号：静态资源用 ?v= 做缓存破坏；发版后按需 purge 首页与关键 CSS/JS。
4. 自检比工具链花哨更重要：构建后断言首页关键区块数量，避免脚本重复注入把 UI 弄坏。

Workers / Agents SDK 面向「在平台上执行代码」；对文档站而言，优先保证 可复现的静态构建 与 可回滚的部署 ID。

怎么做

可把流程固定成两步，失败时容易定位：

# 1) 构建
./scripts/publish.sh

# 2) 上传 + 部署（本站既有 JWT + blake3 Direct Upload 流程）
# 记录返回的 deploy_id，方便回滚与核对 preview URL

核对清单建议写进团队习惯：

• 打开线上首页，确认 proof-stats / 常用工具各只有一块。
• 打开一个 Tools 落地页，确认 ?v= 已升到本版。
• 打开 Pages preview URL 与自定义域名各一次，排除边缘缓存误导。

若使用官方 wrangler pages deploy，本质同样是「本地目录 → Pages 项目」；选择 CLI 还是 API，取决于是否已有自动化封装。关键是 不要把密钥写进前端静态文件。

和本站工具

发版或排障时，令牌、状态码、连接信息经常要在本地先看清楚，再决定是否交给脚本：

• JWT 解码：只解码 Header/Payload，便于确认上传令牌字段（不做验签）。
• HTTP 状态码：核对边缘返回是否异常。
• 连接串解析：若流水线还碰数据库，先拆清主机与库名，避免连错环境。

以上工具均为浏览器本地运算，默认不上传输入内容。

发版节奏上也建议「小步、可回滚」：一次只合入一类改动（例如只动 Tools SEO，或只加速记），构建日志里保留 article/tool 数量，异常立刻停。自定义域名若开了代理，purge 要覆盖首页与带 ?v= 的资源 URL，否则浏览器可能仍吃旧 CSS，看起来像「版式没更新」。

对个人站而言，不必一上来就上复杂预览环境矩阵；Pages 每次部署自带 preview URL，用它做视觉核对，确认无误再看生产域名。若构建脚本会改首页，务必保留「区块数量断言」——这是 0xKEV 踩过重复注入后留下的硬约束。

把「构建成功」和「用户看到的站点正确」当成两件不同的事来验收，能少掉大半发版焦虑。

小结

静态站的竞争力在于 构建可重复、部署可审计、缓存可理解。Cloudflare 的 CLI/API 只是搬运工；真正要守住的是产物质量与发版自检。0xKEV 用同一套路：文档与工具页静态化，发版后留下 deploy_id，出问题能回滚。