常见问题

以下是关于 Browser Run（曾用名 Browser Rendering）最常见问题的解答。

有关定价问题，请访问定价常见问题。 有关使用限制问题，请访问限制常见问题。 如果找不到所需答案，请加入我们的 Discord ↗。

此错误通常是因为 Puppeteer 启动时未收到 browser 绑定。要解决此错误，请将 browser 绑定传入 puppeteer.launch。

此错误（Unable to create new browser: code: 429: message: Browser time limit exceeded for today）表示你已达到 Workers Free 套餐的每日浏览器实例限制。Workers Free 账户每天浏览器使用时间上限为 10 分钟。超过该限制后，进一步的创建尝试将返回 429 错误，直到下一个 UTC 日。

要解决此错误，请升级到 Workers Paid 套餐，该套餐允许每天使用超过 10 分钟并具有更高的限制。如果你最近已升级但仍看到此错误，请尝试重新部署 Worker 以确保用量正确关联到新套餐。

422 Unprocessable Entity 错误通常表示 Browser Run 因网站问题无法完成操作。

这可能发生在以下情况：

• 网站在渲染期间消耗过多内存。
• 页面本身崩溃或在操作完成前返回错误。
• 请求超过了页面加载、元素加载或操作的超时限制之一。

此错误最常见的原因是超时。你可以在 Quick Actions 超时参考 中查看不同的计时器及其限制。

如果屏幕截图、PDF 或抓取的内容缺少在浏览器中查看页面时出现的元素，可能是因为 Browser Run 捕获输出时页面尚未完成加载。

JavaScript 密集型页面和单页应用（SPA）通常在初始 HTML 解析后动态加载内容。默认情况下，Browser Run 等待 domcontentloaded，该事件在 JavaScript 完成页面渲染之前触发。

要解决此问题，请使用 goToOptions.waitUntil 参数，并设置为以下值之一：

Quick Actions 示例：

{
	"url": "https://example.com",
	"goToOptions": {
		"waitUntil": "networkidle2"
	}
}

如果内容仍然缺失：

• 使用 waitForSelector 等待特定元素出现后再捕获。
• 对于加载较慢的页面，增大 goToOptions.timeout（最高 60 秒）。
• 检查页面是否需要身份验证或对 bot 返回不同内容。

完整参考请参阅 Quick Actions 超时。

在本地运行浏览器适用于开发和小规模任务，但对生产工作负载有实际限制。

使用 Browser Run，浏览器会话在 Cloudflare 基础设施上运行，因此自动化无需本地机器。无需维护 Chrome 安装、无需保持 VM 运行，会话按需启动并在完成后关闭。

你还可以使用 Cloudflare Queues 异步处理批量 URL，大规模爬取而无需自行管理队列基础设施。

浏览器会话在 Cloudflare 全球网络上、靠近传入请求的位置开启。Browser Run 是一个 Workers 绑定（binding），因此可直接与 Durable Objects、Queues 以及 Cloudflare 开发者平台的其他产品集成。

尚不支持。本地开发目前有以下限制：

• 不支持大于 1 MB 的请求。

你还可以在本地开发期间以可见（headful）模式运行 Chrome，以可视化调试自动化脚本（实验性）。在启动开发服务器之前设置 X_BROWSER_HEADFUL 环境变量：

X_BROWSER_HEADFUL=true npx wrangler dev

如果你渲染的页面需要身份验证，可以使用以下方法之一传递凭据。这些参数适用于所有 Quick Actions 端点。

HTTP Basic Auth（HTTP 基本认证）：

{
	"authenticate": {
		"username": "user",
		"password": "pass"
	}
}

基于 Cookie 的身份验证：

{
	"cookies": [
		{
			"name": "session_id",
			"value": "abc123",
			"domain": "example.com",
			"path": "/",
			"secure": true,
			"httpOnly": true
		}
	]
}

基于 Token 的身份验证：

{
	"setExtraHTTPHeaders": {
		"Authorization": "Bearer your-token"
	}
}

有关所有三种方法的完整工作示例，请参阅截取已认证页面的屏幕截图。

是的，Browser Run 请求始终被 Cloudflare 识别为 bot 流量。Cloudflare 默认不强制执行 bot 防护——这是客户的选择。

如果你尝试扫描自己的 zone 并希望 Browser Run 不受 bot 防护配置干扰地访问网站，可以创建 WAF 跳过规则来将 Browser Run 加入允许列表。

你必须使用 Enterprise 套餐才能在自己的网站上将 Browser Run 加入允许列表，因为 WAF 自定义规则需要访问 Bot Management 字段。

Browser Run 根据方式使用不同的 bot 检测 ID。使用与你要加入允许列表的方式匹配的 ID。

否。Browser Run 请求源自 Cloudflare 全球网络，你无法配置按请求 IP 轮换。所有渲染流量来自 Cloudflare IP 范围，请求包含自动请求头，如 cf-biso-request-id 和 cf-biso-devtools，以便源服务器识别它们。

每个浏览器会话的请求数没有固定限制。只要保持在可用的计算和内存限制内，单个浏览器可以处理多个请求。

可以。如果网页或 PDF 需要未预装的字体，你可以使用 addStyleTag 在渲染时加载自定义字体。这适用于 Quick Actions、Puppeteer 和 Playwright。有关说明和示例，请参阅自定义字体。

若遇到并发限制，或希望优化并发浏览器使用，可参考以下建议：

• 使用标签页或共享浏览器优化：与其为每个任务启动新浏览器，不如在同一浏览器实例中打开多个标签页或运行多个操作。
• 复用会话：通过复用会话而非每次启动新浏览器，可优化配置并缩短启动时间。若需保持测试隔离（例如依赖干净环境的测试），建议使用无痕浏览器上下文 ↗，其 cookies 和缓存与其他会话隔离。

若仍遇到并发限制，可申请提高限额 ↗。

对于大多数工作负载，复用现有浏览器会话并打开新标签页，而非为每个任务启动新浏览器。Browser Run 将浏览器实例计入你的并发浏览器和新浏览器实例速率限制，但现有会话内的标签页不计入任一限制。复用会话还可以避免启动新浏览器的冷启动成本。

单个浏览器可以运行许多标签页，但所有标签页共享同一个浏览器进程和内存。重型页面（例如具有大型 JavaScript 包、媒体或复杂 DOM 的页面）每个标签页消耗更多内存，因此在同一浏览器中打开过多标签页可能导致崩溃。测试你的工作负载以找到每个浏览器的安全标签页数量。对于轻量页面，数十个标签页可能没问题。对于重型页面，可能只有几个。

如果你复用会话但仍需要在任务之间隔离，请使用无痕浏览器上下文。无痕上下文将 cookies、local storage 和 cache 彼此隔离，也与默认上下文隔离，因此你可以在同一浏览器的标签页中运行独立任务而不会数据泄漏。

import puppeteer from "@cloudflare/puppeteer";

const browser = await puppeteer.connect(env.MYBROWSER, sessionId);
// or await puppeteer.launch(env.MYBROWSER);

const context = await browser.createBrowserContext();
const page = await context.newPage();

import { connect } from "@cloudflare/playwright";

const browser = await connect(env.BROWSER, sessionId);
// or use the browser returned by acquire()

const context = await browser.newContext();
const page = await context.newPage();

仅当你需要完整的进程级隔离、不同的浏览器配置，或浏览器变得不稳定后，才打开新浏览器。对于自动化屏幕截图、抓取和爬取工作负载，复用会话和标签页通常是正确选择。Quick Actions 自动管理会话和标签页，因此你无需自行处理复用。

对于 Quick Actions（``/crawl` 端点 除外）、Puppeteer、Playwright 和 CDP，Cloudflare 临时处理内容，不会保留客户提交的 HTML 或生成的输出（如 PDF 或屏幕截图），超出执行渲染操作所需的范围。响应返回后，内容会立即从渲染环境中丢弃。

有两种情况数据会在会话之外保留：

• Crawl 端点：``/crawl` Quick Actions 端点 异步运行任务，因此任务结果（包括 HTML、Markdown 或 JSON 格式的爬取页面内容）在任务完成后存储 14 天，之后数据被删除。爬取任务最长运行时间为七天。
• 会话录制：Puppeteer、Playwright 和 CDP 会话支持可选的会话录制功能。启用后，DOM 变更、鼠标和键盘事件以及页面导航被捕获为结构化 JSON 事件并保留 30 天。输入字段内容默认被掩码。录制可通过仪表板和 API 访问，并在保留期后自动删除。

对于 Quick Actions（[``/crawl端点](/browser-run/quick-actions/crawl-endpoint/) 除外），生成的内容默认缓存五秒（可通过cacheTTL参数配置最长一天，或设置为0` 禁用缓存）。此缓存防止同一账户对同一 URL 的重复请求。客户提交的 HTML 内容本身不会被缓存。

对于 Puppeteer、Playwright 和 CDP，不使用缓存。内容仅在渲染操作期间存在于内存中，响应返回后立即丢弃。

对于 ``/crawl` 端点，所有爬取任务结果在完成后存储在 R2 中 14 天。