跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

快速入门

最后更新 查看 MarkdownAgent 设置

Cloudflare Browser Run(曾用名 Browser Rendering)允许你以编程方式控制无头浏览器,从而执行截取屏幕截图、生成 PDF 和执行自动化浏览器任务等操作。本指南将帮助你选择正确的集成方式并开始你的第一个项目。

Browser Run 提供两类集成方式:

  • Quick Actions:简单的无状态浏览器任务,如屏幕截图、PDF 和抓取。无需部署代码。
  • Browser Sessions:通过 Puppeteer、Playwright、CDP 或 Stagehand 直接控制浏览器。在 Cloudflare Workers 中部署,或通过 CDP 从任何环境连接。
使用场景 推荐方式 原因
简单的屏幕截图、PDF 或抓取 Quick Actions 无需部署代码;单个 HTTP 请求
浏览器自动化 Playwright、Puppeteer 或 CDP 通过脚本完全控制浏览器
迁移现有脚本 Puppeteer、Playwright 或 CDP 与标准库的代码改动最小
AI 驱动的数据提取 JSON 端点 通过自然语言提示获取结构化数据
全站爬取 Crawl 端点 多页面内容提取,异步返回结果
AI 智能体浏览 Playwright MCP 或 带 MCP 客户端的 CDP LLM 通过 MCP 控制浏览器
弹性抓取 Stagehand AI 按意图而非选择器查找元素
从任何环境直接控制浏览器 CDP 从本地机器、CI/CD 或外部服务器通过 WebSocket 访问

Quick Actions

Quick Actions 可通过 REST API 使用,也可通过 Cloudflare Worker 中的 browser 绑定直接调用。

前提条件

示例:截取屏幕截图

使用以下 curl 命令通过 REST API 从 URL 截取屏幕截图:

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

前提条件

示例:从 Worker 截取屏幕截图

1. 创建 Worker 项目

运行以下命令,创建名为 browser-quick-action 的新 Worker 项目:

npm create cloudflare@latest -- browser-quick-action

设置时,选择以下选项:

  • 对于 What would you like to start with?(希望从什么开始?),选择 Hello World example。
  • 对于 Which template would you like to use?(希望使用哪个模板?),选择 Worker only。
  • 对于 Which language do you want to use?(希望使用哪种语言?),选择 TypeScript。
  • 对于 Do you want to use git for version control?(是否使用 Git 进行版本控制?),选择 Yes。
  • 对于 Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?(是否添加 AGENTS.md 文件以帮助 AI 编程工具理解 Cloudflare API?),选择 Yes。
  • 对于 Do you want to deploy your application?(是否部署应用?),选择 No(部署前还需要进行一些修改)。

2. 配置 browser 绑定

使用 browser 绑定(binding) 更新 Wrangler 配置文件:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "browser-quick-action",
  "main": "src/index.ts",
  "upload_source_maps": true,
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "browser": {
    "binding": "BROWSER"
  }
}
name = "browser-quick-action"
main = "src/index.ts"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-14"

[browser]
binding = "BROWSER"

3. 编写 Worker 代码

将 src/index.ts 的内容替换为以下代码:

export default {
	async fetch(request, env) {
		return await env.BROWSER.quickAction("screenshot", {
			url: "https://example.com",
		});
	},
};
interface Env {
	BROWSER: BrowserRun;
}

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

此 Worker 使用 browser 绑定截取 example.com 的屏幕截图,并直接在响应中返回图像。

4. 测试

运行 npx wrangler dev --remote 在本地测试 Worker。

访问本地 URL 查看屏幕截图。

5. 部署

运行 npx wrangler deploy 将 Worker 部署到 Cloudflare 全球网络。

其他 Quick Actions 端点包括:

查看完整的 Quick Actions 端点 列表。

浏览器会话

浏览器会话让你完全控制无头浏览器。你可以使用 REST API 从任何位置连接,或通过浏览器绑定从 Cloudflare Worker 连接。

前提条件

创建浏览器会话

一次 API 调用即可获得你可以查看并交互的实时浏览器会话:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-rendering/devtools/browser?keep_alive=600000&targets=true" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
Responsejson
{
	"sessionId": "1909cef7-23e8-4394-bc31-27404bf4348f",
	"targets": [
		{
			"devtoolsFrontendUrl": "https://live.browser.run/ui/inspector?wss=..."
		}
	]
}

复制 devtoolsFrontendUrl 并在浏览器中打开。你现在拥有一个运行在 Cloudflare 上、可直接交互的真实浏览器会话:输入 URL、点击页面并检查页面。

你可以使用 CDP、Puppeteer 或 Playwright 从任何环境以编程方式驱动浏览器会话。浏览器会话还支持:

  • Live View:实时查看并交互远程会话,适用于调试自动化脚本或监控浏览器活动。
  • 会话录制:录制浏览器会话以供回放,便于审查自动化运行期间发生的内容。
  • Human in the Loop:暂停自动化并将控制权交给人类,用于需要人工介入的任务,例如解决 CAPTCHA 或完成登录流程。

前提条件

  1. 注册 Cloudflare 账户 ↗。
  2. 安装 Node.js ↗。

Node.js 版本管理器

使用 Vite+ (vp env) ↗ 安装和管理 Node.js 版本。

有关支持的 Node.js 版本,请参阅 Wrangler 系统要求。

示例:导航到 URL、截取屏幕截图并存储到 KV

1. 创建 Worker 项目

Cloudflare Workers 提供无服务器执行环境,可创建新应用或扩展现有应用,无需配置或维护基础设施。Worker 应用是与无头浏览器交互的容器,可执行截图等操作。

运行以下命令创建名为 browser-worker 的新 Worker 项目:

npm create cloudflare@latest -- browser-worker

设置时,选择以下选项:

  • 对于 What would you like to start with?(希望从什么开始?),选择 Hello World example。
  • 对于 Which template would you like to use?(希望使用哪个模板?),选择 Worker only。
  • 对于 Which language do you want to use?(希望使用哪种语言?),选择 JavaScript / TypeScript。
  • 对于 Do you want to use git for version control?(是否使用 Git 进行版本控制?),选择 Yes。
  • 对于 Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?(是否添加 AGENTS.md 文件以帮助 AI 编程工具理解 Cloudflare API?),选择 Yes。
  • 对于 Do you want to deploy your application?(是否部署应用?),选择 No(部署前还需要进行一些修改)。

2. 安装 Puppeteer

在 browser-worker 目录中安装 Cloudflare 的 Puppeteer 分支:

npm i -D @cloudflare/puppeteer

3. 创建 KV 命名空间

Browser Run 可与其他开发者产品配合使用。你可能需要 D1 关系型数据库、用于归档爬取页面和资源的 R2 存储桶、用于保持浏览器实例存活并在多个请求间共享的 Durable Objects,或用于异步处理任务的 Queues。

本示例使用 KV 存储 缓存截图。

创建两个命名空间,分别用于生产和开发。

npx wrangler kv namespace create BROWSER_KV_DEMO
npx wrangler kv namespace create BROWSER_KV_DEMO --preview

记下 ID,供下一步使用。

4. 配置 Wrangler 配置文件

通过添加 browser 绑定(binding) 和 Node.js 兼容性标志 来配置 browser-worker 项目的 Wrangler 配置文件。绑定使 Worker 能够与 Cloudflare 开发者平台上的资源交互。browser binding 名称由你设定,本指南使用 MYBROWSER。browser 绑定使 Worker 与无头浏览器通信,可执行截图、生成 PDF 等操作。

使用 Browser Run API 绑定和已创建的 KV 命名空间更新 Wrangler 配置文件:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "browser-worker",
	"main": "src/index.js",
	"upload_source_maps": true,
	// Set this to today's date
	"compatibility_date": "2026-11-14",
	"compatibility_flags": ["nodejs_compat"],
	"browser": {
		"binding": "MYBROWSER"
	},
	"kv_namespaces": [
		{
			"binding": "BROWSER_KV_DEMO",
			"id": "22cf855786094a88a6906f8edac425cd",
			"preview_id": "e1f8b68b68d24381b57071445f96e623"
		}
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "browser-worker"
main = "src/index.js"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-14"
compatibility_flags = [ "nodejs_compat" ]

[browser]
binding = "MYBROWSER"

[[kv_namespaces]]
binding = "BROWSER_KV_DEMO"
id = "22cf855786094a88a6906f8edac425cd"
preview_id = "e1f8b68b68d24381b57071445f96e623"

5. 代码

用以下 Worker 代码更新 src/index.js:

import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = await page.screenshot();
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
};

用以下 Worker 代码更新 src/index.ts:

import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
	BROWSER_KV_DEMO: KVNamespace;
}

export default {
	async fetch(request, env): Promise<Response> {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img: Buffer;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = (await page.screenshot()) as Buffer;
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
} satisfies ExportedHandler<Env>;

此 Worker 使用 Puppeteer 创建浏览器,打开新页面,导航到“url”参数指定的位置,截取页面截图,将截图存储到 KV,关闭浏览器,并返回截图的 JPEG 图像。

若 Worker 在生产环境运行,截图会存入生产 KV 命名空间。若运行 wrangler dev,则存入开发 KV 命名空间。

若再次请求相同 url,将使用 KV 中的缓存版本(除非已过期)。

6. 测试

运行 npx wrangler dev 在本地测试 Worker。

要测试首次截图,访问以下 URL:

<LOCAL_HOST_URL>/?url=https://example.com

7. 部署

运行 npx wrangler deploy 将 Worker 部署到 Cloudflare 全球网络。

要获取首次截图,访问以下 URL:

<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?url=https://example.com

后续步骤

如有功能请求或发现 bug,请加入 Cloudflare Developers Discord 社区 ↗ 直接向 Cloudflare 团队反馈。

这篇文档对您有帮助吗?