用 Wrangler 部署 Cloudflare Worker

---
name: deploy-cloudflare-worker-workflow
description: "验证配置和构建输出，先本地或预览检查，再只向明确环境部署并完成验证。"
---

# 部署 Cloudflare Worker

## 适用目标

把 Worker 发布到指定账户和环境，并保留明确的回滚目标。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **Cloudflare Wrangler**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 4.87.0）
  - 安装：`npm install --save-dev wrangler`
  - 认证：OAuth, API token
  - 最小权限：API Token 仅授权任务所需账号、Zone 和 Worker 资源。
- **curl**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 8.7.1）
  - 安装：`brew install curl`
  - 认证：none, basic, bearer token, client certificate, netrc
  - 最小权限：通过环境变量提供范围受限的 Token，不要在输出中打印请求密钥。
- **jq**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 jq-1.7.1-apple）
  - 安装：`brew install jq`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。

## 输入合同

- Worker 仓库
- Wrangler 配置
- 明确的账户与环境
- 最小权限 API Token

## 输出合同

- 构建结果
- 预览或本地检查
- Deployment ID 与 URL
- 线上验证报告

## 安全工作流

1. **检查配置** — 读取脚本、Worker 名称、兼容设置、binding 和目标环境，不打印密钥。
   - 输入: 仓库和 Wrangler 配置
   - 输出: 部署目标与必需 binding
   - 风险: `local-write`
   - 命令: `wrangler deploy --dry-run --outdir /tmp/worker-build`
2. **执行预览检查** — 通过本地或预览路径请求 Worker，并记录预期响应。
   - 输入: 已构建 Worker 和测试请求
   - 输出: 预览证据与未解决警告
   - 风险: `read-only`
3. **部署并验证** — 批准后部署到指定环境，保存 deployment 标识并测试线上 URL。
   - 输入: 批准的目标和限定 Token
   - 输出: 部署结果和线上检查
   - 风险: `remote-write`
   - 命令: `wrangler deploy --env production`

## 必须先确认

- 部署任何共享或生产环境
- 创建或修改 Secret、路由、域名、D1、KV、R2 等 binding
- 执行数据库迁移

## 回滚

- 发布前记录上一个 deployment
- 按 Wrangler 当前文档使用账户支持的 rollback 路径
- 定位原因后再回退代码或配置并重新部署

## 官方来源

- [Cloudflare Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/) — 用于核对当前命令、认证、输出和操作边界。
- [curl manual](https://curl.se/docs/manpage.html) — 用于核对当前命令、认证、输出和操作边界。