测试与调试

Preview 支持与生产相同的 Workers Observability 功能 — 日志、trace、指标 和 Tail Worker — 可独立配置，使 Preview 遥测与生产分离。

在 previews 块中为 Preview 启用日志和 trace。这些设置与生产独立，因此你可以在 Preview 上使用全量采样，而不影响生产遥测。

{
  "observability": {
    "enabled": true,
    "logs": { "enabled": true, "invocation_logs": true }
  },
  "previews": {
    "observability": {
      "enabled": true,
      "logs": {
        "enabled": true,
        "invocation_logs": true,
        "persist": true
      },
      "traces": {
        "enabled": true,
        "head_sampling_rate": 1,
        "persist": true
      }
    }
  }
}

[observability]
enabled = true

  [observability.logs]
  enabled = true
  invocation_logs = true

[previews.observability]
enabled = true

  [previews.observability.logs]
  enabled = true
  invocation_logs = true
  persist = true

  [previews.observability.traces]
  enabled = true
  head_sampling_rate = 1
  persist = true

启用后，Preview 的日志和 trace 会出现在 Cloudflare 仪表板中单个 Preview 的 Observability 选项卡下。你也可以在仪表板的 Settings > Observability 中按 Preview 配置这些设置。

Tail Worker 会接收 Worker 的执行元数据 — 请求 URL、响应状态码、console 日志和错误。你可以为生产、Preview 或两者配置 Tail Worker 目标。

{
  "tail_consumers": [
    { "service": "my-tail-sink" }
  ],
  "previews": {
    "tail_consumers": [
      { "service": "my-tail-sink" }
    ]
  }
}

[[tail_consumers]]
service = "my-tail-sink"

[[previews.tail_consumers]]
service = "my-tail-sink"

使用 npx wrangler preview --json 部署 Preview 时，输出会确认是否已附加 Tail Worker 目标。你也可以在仪表板的 Settings > Observability > Tail Worker 中按 Preview 配置 Tail Worker 目标。

Preview 调用指标可通过 GraphQL Analytics API 获取。查询 workersInvocationsAdaptive 数据集，并使用 isPreview: 1 过滤 Preview 流量。

query PreviewMetrics($accountTag: String!, $since: Time!) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			workersInvocationsAdaptive(
				limit: 100
				filter: { datetime_geq: $since, isPreview: 1 }
			) {
				dimensions {
					datetime
					scriptName
					previewSlug
					status
				}
				sum {
					requests
					errors
				}
			}
		}
	}
}

有用字段包括 scriptName（Worker 名称）、previewSlug（Preview 名称）和 status。

每个 Preview 的指标也可在仪表板中该 Preview 的 Metrics 选项卡下查看。

你还可以使用 Cloudflare API MCP server 查询 Preview 可观测性数据。

Preview 可观测性展示 Worker 内部发生了什么。Browser Run 可以为同一变更补充浏览器侧视图 — 打开 Preview URL、走完一个流程，并捕获截图或 PDF。

在 URL 或请求标头中包含 debug ID，以便将浏览器流量与 Preview 在 Workers Observability 中的日志和 trace 关联。

# Deploy the Preview
npx wrangler preview --name my-feature

# Capture a screenshot of the Preview URL
curl "https://YOUR_BROWSER_RUN_WORKER.workers.dev/screenshot?url=https://my-feature-my-worker.subdomain.workers.dev&debugId=review-123"

Browser Run 不是必需的 — 你也可以使用 curl、Playwright、集成测试或任何其他工具向 Preview URL 发送流量。当你希望审查产物包含浏览器实际渲染的内容时，Browser Run 很有用。

有关创建 Preview URL、探测它、捕获截图或将其发回拉取请求的 GitHub Actions 示例，请参阅示例。

你可以使用 符合 OpenTelemetry 的导出 或 Workers Logpush 将 Preview 遥测导出到现有可观测性栈。在 previews 块中配置这些导出，以将其与生产分开。

• wrangler tail 不支持指定 Preview。