快速入门 · Cloudflare Browser Run docs

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 绑定直接调用。

前提条件

注册 Cloudflare 账户 ↗。
创建具有 Browser Rendering - Edit 权限的 Cloudflare API Token。

示例：截取屏幕截图

使用以下 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"

前提条件

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

示例：从 Worker 截取屏幕截图

1. 创建 Worker 项目

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

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

yarn create cloudflare browser-quick-action

pnpm 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?，选择 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",
  // Set this to today's date
  "compatibility_date": "2026-08-17",
  "browser": {
    "binding": "BROWSER"
  }
}

name = "browser-quick-action"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"

[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 端点列表。

浏览器会话

前提条件

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

Node.js 版本管理器

使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器，以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。

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

1. 创建 Worker 项目

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

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

npm create cloudflare@latest -- browser-worker

yarn create cloudflare browser-worker

pnpm 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?，选择 Yes。
对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。

2. 安装 Puppeteer

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

npm i -D @cloudflare/puppeteer

yarn add -D @cloudflare/puppeteer

pnpm add -D @cloudflare/puppeteer

bun add -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",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"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"
# Set this to today's date
compatibility_date = "2026-08-17"
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

后续步骤

查看所有 Quick Actions 端点
试用 Playwright MCP
使用 CDP 从任何环境连接
了解更多关于 Browser Run 限制和定价的信息

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