cloudflare-workers-publish

Cloudflare Workers 发布

使用 Static Assets 将静态 HTML 文件（Bokeh 图表、仪表板、报告）部署到 Cloudflare Workers，并使用 1Password 管理凭据。

范围：仅在 workers.dev 上进行静态部署。不涉及动态 Workers 或 R2 对象存储。

前提条件：1Password CLI（brew install 1password-cli）+ Node.js（npx wrangler）

---

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生变化，或需要使用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

• 将 HTML 文件发布到公共 URL（文件太大，无法放在 GitHub 上）
• 设置新的 Cloudflare Workers 静态站点
• 排查 Cloudflare 部署失败的问题
• 在 1Password 中轮换 Cloudflare API 令牌

请勿用于：动态 Workers（JavaScript/TypeScript 逻辑）、Cloudflare Pages（已于 2025 年 4 月弃用 - CFW-01）、R2 对象存储或自定义域名（本文未涵盖高级设置）。

---

架构

Local project/
├── results/published/              # Deploy root (contains wrangler.toml)
│   ├── wrangler.toml               # Workers config (name + assets)
│   ├── index.html                  # Auto-generated directory listing
│   └── gen800/                     # Subdirectories with HTML files
│       └── XRPUSDT_750/
│           └── equity_plot.html    # 13MB Bokeh chart
└── scripts/
    └── publish_findings.sh         # Deploy script (3 phases)

Credential flow:

1Password (Claude Automation vault)
   ├── account_id (TEXT)      →  CLOUDFLARE_ACCOUNT_ID env var
   └── credential (CONCEALED) →  CLOUDFLARE_API_TOKEN env var
                                       ↓
                                 npx wrangler deploy
                                       ↓
                                 https://{name}.{slug}.workers.dev/

---

TodoWrite 任务模板

模板 A - 新建静态站点（首次设置）

1. [Preflight] Verify Node.js and 1Password CLI installed
2. [Preflight] Create Cloudflare API token (Workers Scripts Edit permission)
3. [Execute] Pre-provision 1Password item in Claude Automation vault (biometric)
4. [Execute] Store token + account ID in 1Password item fields
5. [Execute] Create publish directory with wrangler.toml (3 fields only)
6. [Execute] Create deploy script from skill template (parameterize 4 vars)
7. [Execute] Add a moon task wrapper (publish-site) to moon.yml
8. [Execute] Add .wrangler/ to .gitignore
9. [Execute] Add LFS tracking for large HTML files in .gitattributes
10. [Verify] Enable workers.dev subdomain in Cloudflare dashboard
11. [Verify] Run first deploy and verify URL in browser (NOT curl)
12. [Verify] Document the workers.dev URL in project docs

模板 B - 向已发布的现有站点添加文件

1. [Preflight] Verify files are real content, not LFS pointers (head -1)
2. [Execute] Copy HTML files to published/{generation}/{symbol_threshold}/
3. [Execute] Run deploy script (index.html auto-regenerates)
4. [Verify] Verify new files appear at workers.dev URL in browser

模板 C - 新建 Worker（新子域名/项目）

1. [Preflight] Choose worker name ({name}.{slug}.workers.dev)
2. [Execute] Create 1Password item OR reuse existing Cloudflare credentials
3. [Execute] Create wrangler.toml with chosen name and today's date
4. [Execute] Create parameterized deploy script from skill template
5. [Execute] Add a moon task wrapper to moon.yml
6. [Verify] Deploy and discover actual workers.dev URL via wrangler output

模板 D - 轮换 Cloudflare API 令牌

1. [Execute] Create new API token in Cloudflare dashboard (Workers Scripts Edit)
2. [Execute] Update 1Password item credential field (biometric required)
3. [Verify] Run deploy script to verify new token works
4. [Execute] Revoke old token in Cloudflare dashboard

模板 E - 排查部署失败问题

1. Is wrangler.toml in current directory? (CFW-10)
2. Are credentials populated? Print first 8 chars of account ID
3. Is --reveal present for CONCEALED fields? (CFW-03)
4. Is workers.dev subdomain registered in CF dashboard? (CFW-07)
5. Does token have Workers Scripts Edit permission? (CFW-11)
6. Are HTML files real content or LFS pointers? head -1 file (CFW-12)
7. SSL handshake error? Verify in browser, not curl (CFW-08)
8. Is npx wrangler installed? npx wrangler --version

---

工作流：首次设置

阶段 1：创建 Cloudflare API 令牌

1. 前往 https://dash.cloudflare.com/profile/api-tokens
2. 点击 Create Token > Custom token
3. 设置权限：Account > Workers Scripts > Edit（CFW-11）
4. 账户资源：Include > 你的账户
5. 复制令牌（仅显示一次）

阶段 2：配置 1Password 凭据

重要（CFW-02）：1Password 服务账号只能读取项目，无法创建新项目。请先手动创建项目。

请参阅 1Password 设置指南，了解分步说明。

配置完成后，项目应包含以下内容：

字段	类型	--reveal	内容
account_id	文本	否	Cloudflare 账户 ID
credential	隐藏	是	API 令牌

阶段 3：创建 wrangler.toml

请参阅 wrangler 设置指南。

# Minimal Workers Static Assets config (CFW-09)
name = "my-project-name"
compatibility_date = "2026-02-18"

[assets]
directory = "."

阶段 4：创建部署脚本

复制随附的模板，并编辑 4 个配置变量：

cp "$(skill-path)/scripts/publish_static.sh" scripts/publish_myproject.sh
# Edit: PUBLISH_DIR, OP_ITEM_ID, SITE_TITLE, PROJECT_URL

也可参考可用的实现：rangebar-patterns/scripts/publish_findings.sh

阶段 5：创建 moon 任务

# moon.yml (CFW-13: bash in a .sh file, not inline in the task command)
tasks:
  publish-site:
    command: 'bash scripts/publish_myproject.sh'
    options:
      cache: false

如果仓库尚无 moon 工作区，请使用 Skill(itp:bootstrap-monorepo) 初始化，或直接运行脚本：bash scripts/publish_myproject.sh。

阶段 6：Git 文件管理

.gitignore：

# Wrangler temp files (Cloudflare Workers deploy)
.wrangler/
results/published/.wrangler/

.gitattributes（用于大型 HTML 文件）：

results/published/**/*.html filter=lfs diff=lfs merge=lfs -text

阶段 7：启用 workers.dev 子域名（CFW-07）

首次使用的 Cloudflare 账户必须启用 workers.dev 路由：

1. 前往 https://dash.cloudflare.com > Workers & Pages
2. 启用 workers.dev 子域名

子域名无法预测（CFW-06）。部署后请查询你的子域名：

npx wrangler whoami

阶段 8：部署并验证

moon run <project>:publish-site

请在浏览器中验证，而非使用 curl（CFW-08）。macOS LibreSSL 可能无法与 Cloudflare 完成 TLS 握手，但浏览器可以正常处理。

---

反模式概要

完整详情及代码示例请参阅：references/anti-patterns.md

ID	严重性	易踩的坑	修复方法
CFW-01	HIGH	Cloudflare Pages 已弃用（2025 年 4 月）	改用带静态资源的 Workers
CFW-02	HIGH	1P 服务账号创建条目	通过生物识别验证／网页 UI 预先创建
CFW-03	HIGH	CONCEALED 字段缺少 --reveal	对 API 令牌始终传入 --reveal
CFW-04	MEDIUM	SC2155 export VAR=$(cmd)	拆分为：VAR=$(cmd)，然后执行 export VAR
CFW-05	LOW	在 macOS 上使用 Bash 4+ 的 ${var^^}	使用 tr '[:lower:]' '[:upper:]'
CFW-06	MEDIUM	假设 workers.dev URL 格式	运行 npx wrangler whoami 以查找 slug
CFW-07	HIGH	尚未注册 workers.dev 子域名	先在 Cloudflare 控制面板中启用
CFW-08	LOW	macOS 上 curl SSL/TLS 握手失败	改用浏览器验证
CFW-09	MEDIUM	过度复杂化 wrangler.toml	只需 name、compatibility_date、[assets]
CFW-10	HIGH	从错误的目录运行 wrangler	始终先 cd 到包含 wrangler.toml 的目录
CFW-11	MEDIUM	令牌权限过多	仅授予 Workers Scripts Edit（账户）权限
CFW-12	HIGH	部署 LFS 指针而非文件	部署前运行 git lfs pull
CFW-13	MEDIUM	在任务运行器配置中内联 bash	将复杂的 bash 脚本放入独立的 .sh 文件
CFW-14	MEDIUM	while-read 中管道子 shell 导致数据丢失	使用 < <(find ...) 进程替换
CFW-15	LOW	没有目录列表页面	每次部署前自动生成 index.html
CFW-16	HIGH	资源 > 25 MiB → 部署报错 Asset too large	Workers Static Assets 将每个文件的大小硬性限制为 25 MiB。将大型 ZIP／二进制文件托管到大型文件托管服务（R2、GitHub Release、自有服务）；Workers 上仅保留 ≤25 MiB 的文件。参见大型文件与 ZIP 分发
CFW-17	LOW	需要批量下载 ZIP，但文件超过大小上限	缩小 ZIP 档位以符合上限（例如 heic-to-jpeg-bundle --zip-cap-mib 25），或拆分托管位置：在 Workers 上托管图库和小型 ZIP，在 R2 上托管全分辨率 ZIP

---

大文件与 ZIP 交付（下载文件，而不仅是页面）

此技能还涵盖从 Workers 提供可下载文件（ZIP 压缩包、数据集），文件大小上限为 25 MiB，以及使用网关密码保护未公开下载内容的模式。完整指南： references/large-files-and-zip-delivery.md。

快速规则：

• ≤ 25 MiB → Workers 没问题。 小型或缩小后的 ZIP 可以与图库放在一起，并直接链接。> 25 MiB 会导致部署错误（CFW-16）——此类文件请使用 R2、GitHub Release 或自己的主机。
• 密码保护的未公开下载。 加密 ZIP（使用 ZipCrypto，因此 Windows/7-Zip/macOS 可原生打开），并且只在你分享的网关上提供密码（例如 gist、电子邮件），绝不要放在 Workers 页面上。这样，即使找到 ZIP 的裸 URL，也不足以打开文件。heic-to-jpeg-bundle 技能可生成这种受大小上限约束、可选择加密的 ZIP。

---

参考实现

生产环境中的可运行部署位于 rangebar-patterns：

文件	用途
results/published/wrangler.toml	最精简的 Workers 配置
scripts/publish_findings.sh	三阶段部署脚本
.gitignore（.wrangler/）	忽略 wrangler 临时文件
.gitattributes	HTML 的 LFS 跟踪

线上 URL：https://rangebar-findings.terry-301.workers.dev/

---

修改后检查清单

修改此技能后：

1. 反模式表与 references/anti-patterns.md 一致
2. 所有 bash 示例都使用 set -euo pipefail
3. 未硬编码 1Password 项目 ID（均已参数化）
4. 未硬编码 workers.dev 名称（均在运行时发现）
5. 模板脚本通过 bash -n 语法检查
6. 所有内部链接均使用相对路径（./references/...）
7. 链接验证器通过
8. 技能验证器通过
9. 将更改追加到 references/evolution-log.md

---

故障排除

问题	原因	解决方案
op item get 返回掩码内容	缺少 --reveal 标志（CFW-03）	为隐藏字段添加 --reveal
op item create 失败	服务账户无法创建（CFW-02）	先使用生物识别 op 或 Web UI 创建项目
wrangler：找不到配置	所在目录不正确（CFW-10）	部署前 cd 到包含 wrangler.toml 的目录
SSL 握手失败	macOS LibreSSL（CFW-08）	在浏览器中验证；忽略 curl 错误
workers.dev URL 返回 403	未启用子域（CFW-07）	在 Cloudflare 控制面板中启用 Workers & Pages
部署成功，但文件缺失	部署了 LFS 指针（CFW-12）	部署前运行 git lfs pull
${var^^} 语法错误	macOS 上的 Bash 3（CFW-05）	使用 tr '[:lower:]' '[:upper:]'
任务命令被破坏或失败	任务配置中的内联 bash（CFW-13）	将复杂 bash 移至独立的 .sh 文件
index.html 为空	未找到 gen*/*.html 文件	检查文件路径是否符合 find . -path './gen*/*.html' 模式
令牌权限被拒绝	令牌范围错误（CFW-11）	使用 Account > Workers Scripts > Edit 权限重新创建

执行后的反思

此技能执行完毕后，请在结束任务前进行反思：

0. 确认自身位置。 — 编辑前，查找此 SKILL.md 的规范路径（使用 Glob 搜索此技能的名称）。所有修正都针对此文件及其同级的 references/ — 绝不修改其他文档。
1. 哪里失败了？ — 修复导致问题的指令。如果问题可能再次出现，请将其列为反模式。
2. 哪些做得比预期更好？ — 将其提升为推荐实践，并记录原因。
3. 哪里出现了偏差？ — 任何与实际情况不符的脚本、参考资料或外部依赖，都要立即修正。
4. 记录下来。 — 每项更改都要在演进日志中记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切