/snapshot - 捕获多种页面格式 · Cloudflare Browser Run docs

Browser Run 为 HTML 内容、屏幕截图、Markdown 等提供单独的端点。/snapshot 端点将多种格式合并为单个请求，因此你无需分别调用每个端点。默认情况下，它返回 HTML 内容和屏幕截图。你可以使用 formats 参数自定义包含哪些格式，例如在响应中添加 Markdown 和无障碍树。

可通过两种方式使用此端点：

REST API：创建自定义 API Token，并授予 Browser Rendering - Edit 权限。
Workers 绑定：通过 Workers 绑定从 Cloudflare Worker 直接调用端点。无需 API token。

更多信息请参阅 Quick Actions：开始之前。

端点

https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot

必填字段

必须提供 url 或 html 之一：

url（字符串）
html（字符串）

常见使用场景

在单个 API 调用中同时捕获渲染后的 HTML 和视觉屏幕截图
将页面与视觉和结构数据一起归档
构建比较视觉和 DOM 随时间差异的监控工具

基本用法

从 URL 捕获快照

前往 https://example.com/。
注入自定义 JavaScript。
捕获渲染后的 HTML。
截取屏幕截图。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addScriptTag": [
      { "content": "document.body.innerHTML = \"Snapshot Page\";" }
    ]
  }'

{
	"success": true,
	"result": {
		"screenshot": "Base64EncodedScreenshotString",
		"content": "<html>...</html>"
	}
}

import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"],
});

const snapshot = await client.browserRendering.snapshot.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	addScriptTag: [{ content: 'document.body.innerHTML = "Snapshot Page";' }],
});

console.log(snapshot.content);

interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("snapshot", {
			url: "https://example.com/",
			addScriptTag: [{ content: 'document.body.innerHTML = "Snapshot Page";' }],
		});
	},
} satisfies ExportedHandler<Env>;

高级用法

从自定义 HTML 创建快照

此示例使用 html 属性渲染 <html><body>Advanced Snapshot</body></html> 并执行以下操作：

禁用 JavaScript。
将屏幕截图设置为 fullPage。
更改页面大小（viewport）。
等待最多 30000ms 或直到触发 DOMContentLoaded 事件。
返回渲染后的 HTML 内容和页面的 base-64 编码屏幕截图。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "<html><body>Advanced Snapshot</body></html>",
    "setJavaScriptEnabled": false,
    "screenshotOptions": {
       "fullPage": true
    },
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "gotoOptions": {
      "waitUntil": "domcontentloaded",
      "timeout": 30000
    }
  }'

{
	"success": true,
	"result": {
		"screenshot": "Base64EncodedScreenshotString",
		"content": "<html><body>Advanced Snapshot</body></html>"
	}
}

选择返回哪些格式

使用 formats 参数控制响应中包含页面的哪些表示形式。接受的值为 "content"、"screenshot"、"markdown" 和 "accessibilityTree"。如果省略，默认为 ["content", "screenshot"]。

你必须请求至少两种格式。如果只需要单一格式，请改用相应的单格式端点：/content、/screenshot、/markdown 或 /accessibilityTree。

以下示例在一次调用中请求屏幕截图、Markdown 和无障碍树：

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "formats": ["screenshot", "markdown", "accessibilityTree"]
  }'

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "heading",
					"name": "Example Domain",
					"level": 1
				},
				{
					"role": "StaticText",
					"name": "This domain is for use in documentation examples without needing permission. Avoid use in operations."
				},
				{
					"role": "link",
					"name": "Learn more"
				}
			]
		},
		"screenshot": "iVBORw0KGgoAAAANSUhEUgAAB4AAAAQ4CAIAAAB...",
		"markdown": "# Example Domain\n\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\n\n[Learn more](https://iana.org/domains/example)"
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"],
});

const snapshot = await client.browserRendering.snapshot.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	formats: ["screenshot", "markdown", "accessibilityTree"],
});

console.log(snapshot.markdown);
console.log(snapshot.accessibilityTree);

interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("snapshot", {
			url: "https://example.com/",
			formats: ["screenshot", "markdown", "accessibilityTree"],
		});
	},
} satisfies ExportedHandler<Env>;

改善模糊屏幕截图的分辨率

如果设置了较大的视口宽度和高度，屏幕截图可能看起来模糊或像素化。这可能是因为浏览器的默认 deviceScaleFactor（默认为 1）对于该视口来说不够高。

要解决此问题，请增大 deviceScaleFactor 的值。

{
  "url": "https://cloudflare.com/",
  "viewport": {
    "width": 3600,
    "height": 2400,
    "deviceScaleFactor": 2
  }
}

处理 JavaScript 密集型页面

对于 JavaScript 密集型页面或单页应用（SPA），默认的页面加载行为可能返回空或不完整的结果。这是因为浏览器在 JavaScript 完成渲染内容之前就认为页面已加载完毕。

最简单的解决方案是将 gotoOptions.waitUntil 参数设置为 networkidle0 或 networkidle2：

{
	"url": "https://example.com",
	"gotoOptions": {
		"waitUntil": "networkidle0"
	}
}

如需更快响应，高级用户可使用 waitForSelector 等待特定元素，而非等待所有网络活动停止。这需要了解哪个 CSS 选择器表示所需内容已加载。更多详情，请参阅 Quick Actions 超时。

设置自定义 User Agent

可在 JSON 请求体的顶层传入 userAgent 参数，在页面级别更改 user agent。当目标网站根据 user agent 返回不同内容时很有用。

故障排除

如有疑问或遇到错误，请参阅 Browser Run 常见问题与故障排除指南。