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 可通过 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 ↗。
运行以下命令,创建名为 browser-quick-action 的新 Worker 项目:
npm create cloudflare@latest -- browser-quick-actionyarn create cloudflare browser-quick-actionpnpm 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(部署前还需要进行一些修改)。
使用 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"将 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 的屏幕截图,并直接在响应中返回图像。
运行 npx wrangler dev --remote 在本地测试 Worker。
访问本地 URL 查看屏幕截图。
运行 npx wrangler deploy 将 Worker 部署到 Cloudflare 全球网络。
其他 Quick Actions 端点包括:
查看完整的 Quick Actions 端点 列表。
浏览器会话让你完全控制无头浏览器。你可以使用 REST API 从任何位置连接,或通过浏览器绑定从 Cloudflare Worker 连接。
- 注册 Cloudflare 账户 ↗。
- 创建具有
Browser Rendering - Edit权限的 Cloudflare API Token。
一次 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"{
"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 或完成登录流程。
- 注册 Cloudflare 账户 ↗。
- 安装
Node.js↗。
Cloudflare Workers 提供无服务器执行环境,可创建新应用或扩展现有应用,无需配置或维护基础设施。Worker 应用是与无头浏览器交互的容器,可执行截图等操作。
运行以下命令创建名为 browser-worker 的新 Worker 项目:
npm create cloudflare@latest -- browser-workeryarn create cloudflare browser-workerpnpm 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(部署前还需要进行一些修改)。
在 browser-worker 目录中安装 Cloudflare 的 Puppeteer 分支:
npm i -D @cloudflare/puppeteeryarn add -D @cloudflare/puppeteerpnpm add -D @cloudflare/puppeteerbun add -d @cloudflare/puppeteerBrowser 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,供下一步使用。
通过添加 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"用以下 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 中的缓存版本(除非已过期)。
运行 npx wrangler dev 在本地测试 Worker。
要测试首次截图,访问以下 URL:
<LOCAL_HOST_URL>/?url=https://example.com
运行 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 团队反馈。