deploy-verify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deploy & Verify

部署与验证

Deploy Cloudflare Workers to an environment and verify the changes work by inferring what to test from recent git changes.

将Cloudflare Workers部署到指定环境，并通过近期git变更推断测试内容，验证变更是否正常运行。

Workflow

工作流程

1. Pre-deploy checks
2. Deploy to target environment
3. Infer verification plan from git diff
4. Run verification
5. Report results (pass/flag issues)

1. 部署前检查
2. 部署到目标环境
3. 根据git diff推断验证方案
4. 执行验证
5. 反馈结果（通过/标记问题）

Step 1: Pre-Deploy Checks

步骤1：部署前检查

Before deploying, verify:

Types pass —
```
tsc --noEmit
```
or project equivalent
Tests pass —
```
npm test
```
/
```
bun test
```
/ project equivalent
No uncommitted changes —
```
git status
```
should be clean (warn if dirty)
Detect environment config — read
```
wrangler.toml
```
/
```
wrangler.jsonc
```
for available environments

bash

undefined

部署前，请验证以下项：

类型检查通过 — 执行
```
tsc --noEmit
```
或项目对应的类型检查命令
测试用例通过 — 执行
```
npm test
```
/
```
bun test
```
或项目对应的测试命令
无未提交的变更 —
```
git status
```
应显示干净状态（如果有未提交变更需发出警告）
检测环境配置 — 读取
```
wrangler.toml
```
/
```
wrangler.jsonc
```
获取可用环境列表

bash

undefined

List available environments from wrangler config

从wrangler配置中列出可用环境

grep -E '^[env.' wrangler.toml | sed 's/[env.(.*)]/\1/'

undefined

grep -E '^[env.' wrangler.toml | sed 's/[env.(.*)]/\1/'

undefined

Step 2: Deploy

步骤2：部署

bash

undefined

bash

undefined

To a named environment (staging, preview, etc.)

部署到指定命名环境（预发布、预览等）

wrangler deploy --env <environment>

To production (default if no --env)

部署到生产环境（未指定--env时默认部署到生产）

wrangler deploy


If the project has multiple Workers (monorepo), detect which one changed:
- Check `git diff --name-only` for paths matching Worker directories
- Only deploy the Worker(s) that changed

wrangler deploy


如果项目是包含多个Worker的单体仓库（monorepo），检测发生变更的Worker：
- 执行`git diff --name-only`查看变更路径，匹配Worker对应的目录
- 仅部署发生变更的Worker

Step 3: Infer Verification Plan

步骤3：推断验证方案

This is the key step. Look at what changed and determine what to verify:

bash

undefined

这是核心步骤。分析变更内容，确定需要验证的项：

bash

undefined

What changed since last deploy?

查看上一次部署后有哪些变更？

git diff HEAD~~1 --name-only git diff HEAD~~1 --stat git log HEAD~1..HEAD --oneline


**Inference rules:**

| Change type | What to verify |
|---|---|
| API route handler changed | Hit that endpoint, check response shape and status |
| Middleware changed | Test requests that flow through it |
| Auth logic changed | Test both authenticated and unauthenticated requests |
| KV/D1/R2 bindings changed | Test read/write operations on those bindings |
| Environment variables referenced | Verify secrets are set: `wrangler secret list --env <env>` |
| CORS or headers changed | Check response headers |
| Error handling changed | Test error paths |
| New route added | Hit the new route, verify 200 + correct response |
| Route removed | Verify it returns 404 |
| Static assets changed | Fetch them and verify content |

git diff HEAD~~1 --name-only git diff HEAD~~1 --stat git log HEAD~1..HEAD --oneline


**推断规则：**

| 变更类型 | 验证内容 |
|---|---|
| API路由处理逻辑变更 | 访问对应端点，检查响应结构和状态码 |
| 中间件逻辑变更 | 测试经过该中间件的请求 |
| 鉴权逻辑变更 | 同时测试已鉴权和未鉴权的请求 |
| KV/D1/R2绑定变更 | 测试这些绑定的读写操作 |
| 引用了环境变量 | 验证密钥已配置：`wrangler secret list --env <env>` |
| CORS或响应头配置变更 | 检查响应头是否符合预期 |
| 错误处理逻辑变更 | 测试错误路径的处理逻辑 |
| 新增路由 | 访问新路由，验证返回200状态码且响应正确 |
| 移除路由 | 验证访问时返回404状态码 |
| 静态资源变更 | 拉取静态资源验证内容是否正确 |

Step 4: Run Verification

步骤4：执行验证

Use

curl

fetch

to test the deployed URL:

bash

undefined

使用

curl

或

fetch

测试部署后的URL：

bash

undefined

Basic health check

基础健康检查

curl -s -o /dev/null -w "%{http_code}" https://<worker-url>/

Check specific endpoint with response body

检查指定端点的响应体

curl -s https://<worker-url>/api/endpoint | jq .

Check response headers

检查响应头

curl -sI https://<worker-url>/api/endpoint

POST with body

带请求体的POST请求

curl -s -X POST https://<worker-url>/api/endpoint
-H "Content-Type: application/json"
-d '{"key": "value"}'


Also check wrangler logs for errors after hitting endpoints:

```bash

curl -s -X POST https://<worker-url>/api/endpoint
-H "Content-Type: application/json"
-d '{"key": "value"}'


访问端点后还需要检查wrangler日志是否有错误：

```bash

Tail logs (run in background, hit endpoints, then check)

追踪日志（后台运行，访问端点后检查日志内容）

wrangler tail --env <environment> --format json

undefined

wrangler tail --env <environment> --format json

undefined

Step 5: Report

步骤5：结果反馈

If all checks pass:

Deploy verified:
- Environment: staging
- URL: https://my-worker-staging.example.workers.dev
- Checks passed:
  - GET /api/stories → 200, response shape correct
  - POST /api/generate → 200, returns stream
  - KV read/write → working

If issues found (flag, don't rollback):

Deploy issues found:
- Environment: staging
- URL: https://my-worker-staging.example.workers.dev
- PASS: GET /api/stories → 200
- FAIL: POST /api/generate → 500
  - Error in logs: "Missing AI binding"
  - Likely cause: AI binding not configured in staging env
- Action needed: Check wrangler.toml [env.staging] AI bindings

Do NOT automatically rollback. Flag the issues and let the user decide.

所有检查通过时：

部署验证通过：
- 环境：预发布
- URL：https://my-worker-staging.example.workers.dev
- 通过的检查项：
  - GET /api/stories → 200，响应结构正确
  - POST /api/generate → 200，返回流式响应
  - KV读写 → 运行正常

发现问题时（仅标记问题，不要自动回滚）：

发现部署问题：
- 环境：预发布
- URL：https://my-worker-staging.example.workers.dev
- 已通过：GET /api/stories → 200
- 未通过：POST /api/generate → 500
  - 日志错误："Missing AI binding"
  - 可能原因：预发布环境未配置AI绑定
- 需要执行的操作：检查wrangler.toml中[env.staging]的AI绑定配置

请勿自动执行回滚操作。标记问题后让用户自行决定后续操作。

Multi-Environment Patterns

多环境配置模式

Common setup:

toml

undefined

常见配置：

toml

undefined

wrangler.toml

name = "my-worker"

[env.staging] name = "my-worker-staging" route = "staging.example.com/*"

[env.production] name = "my-worker" route = "example.com/*"


**Default flow**: Deploy to staging → verify → user promotes to production.
**Direct to prod**: Only when user explicitly asks. Still run verification after.

name = "my-worker"

[env.staging] name = "my-worker-staging" route = "staging.example.com/*"

[env.production] name = "my-worker" route = "example.com/*"


**默认流程**：部署到预发布环境 → 验证通过 → 用户手动升级到生产环境。
**直接部署到生产**：仅当用户明确要求时执行，部署后仍需执行验证流程。

Secrets

密钥管理

If verification fails with auth/config errors, check that secrets match between environments:

bash

wrangler secret list --env staging
wrangler secret list --env production

Secrets don't copy between environments. A common gotcha after adding a new env.

如果验证时出现鉴权/配置错误，检查不同环境的密钥是否匹配：

bash

wrangler secret list --env staging
wrangler secret list --env production

密钥不会在不同环境间同步。新增环境后这是常见的踩坑点。

Troubleshooting

故障排查

Problem	Fix
500 after deploy	`wrangler tail --env <env>` to see error logs
Binding not found	Check wrangler.toml — bindings must be declared per environment
Secret missing	`wrangler secret put <NAME> --env <env>`
Old code still serving	Worker may be cached — wait 30s or check `wrangler deployments list`
Route not matching	Verify route patterns in wrangler.toml match the URL you're hitting
CORS errors	Check if the Worker sets appropriate CORS headers for the origin

问题	解决方案
部署后返回500	执行 `wrangler tail --env <env>` 查看错误日志
找不到绑定	检查wrangler.toml — 绑定必须按环境单独声明
密钥缺失	执行 `wrangler secret put <NAME> --env <env>`
仍在提供旧版本代码	Worker可能被缓存 — 等待30秒或执行 `wrangler deployments list` 检查部署记录
路由不匹配	验证wrangler.toml中的路由规则是否与你访问的URL匹配
CORS错误	检查Worker是否为请求源设置了合适的CORS头