cloudflare-browser-rendering

Cloudflare Browser Rendering - 完整参考

用于构建 Cloudflare Browser Rendering 浏览器自动化工作流的生产就绪知识领域。

状态：已可用于生产 ✅ 最后更新：2025-11-25 依赖项：cloudflare-worker-base（用于 Worker 设置） 最新版本：@cloudflare/[email protected]、@cloudflare/[email protected]、[email protected]、@cloudflare/[email protected]

---

目录

1. 快速开始（5 分钟）
2. Browser Rendering 概述
3. Puppeteer API 参考
4. Playwright API 参考
5. 会话管理
6. 常见模式
7. 定价与限制
8. 预防已知问题
9. 生产检查清单

---

快速开始（5 分钟）

1. 添加浏览器绑定

wrangler.jsonc：

{
  "name": "browser-worker",
  "main": "src/index.ts",
  "compatibility_date": "2023-03-14",
  "compatibility_flags": ["nodejs_compat"],
  "browser": {
    "binding": "MYBROWSER"
  }
}

为什么需要 nodejs_compat？ Browser Rendering 需要 Node.js API 和 polyfill。

2. 安装 Puppeteer

bun add @cloudflare/puppeteer

3. 截取你的第一张屏幕截图

import puppeteer from "@cloudflare/puppeteer";

interface Env {
  MYBROWSER: Fetcher;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { searchParams } = new URL(request.url);
    const url = searchParams.get("url") || "https://example.com";

    // Launch browser
    const browser = await puppeteer.launch(env.MYBROWSER);
    const page = await browser.newPage();

    // Navigate and capture
    await page.goto(url);
    const screenshot = await page.screenshot();

    // Clean up
    await browser.close();

    return new Response(screenshot, {
      headers: { "content-type": "image/png" }
    });
  }
};

4. 部署

bunx wrangler deploy

在以下地址测试：https://your-worker.workers.dev/?url=https://example.com

重要：

• 始终将 env.MYBROWSER 传递给 puppeteer.launch()（不能是 undefined）
• 完成后始终调用 browser.close()（或使用 browser.disconnect() 以便复用会话）
• 使用 nodejs_compat 兼容性标志

---

何时加载参考资料

用户提及时立即加载：

• puppeteer-api.md → “API 参考”“Puppeteer 方法”“Browser 类”“Page 方法”“完整 API”
• patterns.md → “示例”“如何操作”“屏幕截图”“PDF”“抓取”“自动化”“填写表单”
• session-management.md → “会话”“休眠”“连接池”“状态管理”“Durable Objects”
• pricing-and-limits.md → “成本”“定价”“限制”“配额”“账单”“速率限制”
• common-errors.md → 错误、调试、“无法正常工作”、故障排除、“问题 #4”“问题 #5”“问题 #6”
• puppeteer-vs-playwright.md → “Playwright”“比较”“选择哪个库”“差异”

遇到以下情况时主动加载：

• 构建新的自动化 → 加载 patterns.md
• 调试错误 → 加载 common-errors.md
• 优化成本 → 加载 pricing-and-limits.md
• 管理会话 → 加载 session-management.md
• 需要完整 API → 加载 puppeteer-api.md

---

Browser Rendering 概述

什么是 Browser Rendering？

Cloudflare Browser Rendering 在 Cloudflare 全球网络上提供无头 Chromium 浏览器。你可以使用 Puppeteer 和 Playwright 等熟悉的工具自动执行浏览器任务：

• 屏幕截图 - 捕获网页的可视快照
• PDF 生成 - 将 HTML/URL 转换为 PDF
• 网页抓取 - 从动态网站提取内容
• 测试 - 自动执行前端测试
• 爬取 - 浏览多页工作流

两种集成方式

方式	最适合	复杂度
Workers 绑定	复杂自动化、自定义工作流、会话管理	高级
REST API	简单的屏幕截图/PDF 任务	简单

本文档介绍 Workers 绑定（提供完整 Puppeteer/Playwright API 的高级方式）。

Puppeteer 与 Playwright 对比

特性	Puppeteer	Playwright
API 熟悉度	最受欢迎	采用率不断提升
软件包	@cloudflare/[email protected]	@cloudflare/[email protected]
会话管理	✅ 高级 API	⚠️ 基础
浏览器支持	仅 Chromium	仅 Chromium（尚不支持 Firefox/Safari）
最适用于	屏幕截图、PDF、抓取	测试、前端自动化

建议：大多数情况下使用 Puppeteer。如果你已在测试中使用 Playwright，那么 Playwright 是理想选择。

---

Puppeteer API 参考

浏览器自动化的核心类：

1. 核心函数 - launch()、connect()、sessions()、history()、limits()
2. 浏览器 API - newPage()、sessionId()、close()、disconnect()、createBrowserContext()
3. 页面 API - goto()、screenshot()、pdf()、content()、setContent()、evaluate()、waitForSelector()、type()、click()

快速示例：

const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
await page.goto("https://example.com");
const screenshot = await page.screenshot({ fullPage: true });
await browser.close();

在实现浏览器自动化、网页抓取、调试 Puppeteer 特定问题，或需要完整的 API 签名和方法详情时，加载 references/puppeteer-api.md。

---

Playwright API 参考

Playwright 提供了与 Puppeteer 类似的 API，但存在少许差异。

安装

bun add @cloudflare/playwright

基本示例

import { env } from "cloudflare:test";
import { chromium } from "@cloudflare/playwright";

interface Env {
  BROWSER: Fetcher;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const browser = await chromium.launch(env.BROWSER);
    const page = await browser.newPage();

    await page.goto("https://example.com");
    const screenshot = await page.screenshot();

    await browser.close();

    return new Response(screenshot, {
      headers: { "content-type": "image/png" }
    });
  }
};

与 Puppeteer 的主要区别

特性	Puppeteer	Playwright
导入	import puppeteer from "@cloudflare/puppeteer"	import { chromium } from "@cloudflare/playwright"
启动	puppeteer.launch(env.MYBROWSER)	chromium.launch(env.BROWSER)
会话 API	✅ 高级（会话、历史记录、限制）	⚠️ 基本
自动等待	手动调用 waitForSelector()	内置自动等待
选择器	仅 CSS	CSS、文本、XPath（通过 evaluate 变通实现）

建议：除非你已有需要迁移的 Playwright 测试，否则请继续使用 Puppeteer。

---

会话管理

浏览器会话使用 Durable Objects 管理，以便在多个请求之间持久保存状态。会话支持休眠、自动清理和并发连接处理。

主要模式：

• 会话复用 - 使用 puppeteer.sessions() 和 puppeteer.connect() 复用浏览器
• 浏览器上下文 - 在共享浏览器实例的同时隔离 Cookie 和缓存
• 多个标签页 - 对批量操作使用标签页（newPage()），而非多个浏览器
• 断开连接与关闭 - 使用 disconnect() 保持会话活动，使用 close() 终止会话

如需完整的会话生命周期管理、休眠模式、连接池策略和生产环境示例，请加载 references/session-management.md。

---

常见模式

6 种可用于生产环境的浏览器自动化模式：

1. 使用 KV 缓存截图 - 缓存高流量 URL 的截图，减少浏览器使用量
2. 从 HTML 生成 PDF - 将自定义 HTML 转换为 PDF，用于发票、报告和文档
3. 抓取结构化数据 - 从网页提取产品信息、价格和内容
4. 批量抓取多个 URL - 在单个浏览器中使用标签页高效抓取多个网站
5. AI 增强型抓取 - 将 Browser Rendering 与 Workers AI 结合，实现自适应数据提取
6. 填写表单和自动化操作 - 自动执行登录流程、表单提交和多步骤工作流

快速示例（带缓存的截图）：

const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
await page.goto(url);
const screenshot = await page.screenshot({ fullPage: true });
await env.CACHE.put(url, screenshot, { expirationTtl: 86400 });
await browser.close();

在实现浏览器自动化模式、网页抓取、PDF 生成，或需要包含错误处理和优化的完整生产环境示例时，加载 references/patterns.md。

---

定价与限制

Browser Rendering 按 CPU 时间收费（仅限付费计划）。免费层级：每天 10 分钟。付费层级：每月包含 10 小时，之后每个浏览器小时收费 $0.09，超过 10 个并发浏览器后，每个额外浏览器收费 $2.00。

如需完整的定价层级、配额详情、速率限制策略和成本优化技巧，请加载 references/pricing-and-limits.md。

---

已知问题预防

此技能可预防6 个已记录的问题。以下详细介绍 3 个最关键的错误：

---

问题 #1：不支持 XPath 选择器 ⚠️

错误：“不支持 XPath 选择器”或选择器失败 来源： https://developers.cloudflare.com/browser-rendering/faq/#why-cant-i-use-an-xpath-selector-when-using-browser-rendering-with-puppeteer 原因： XPath 会给 Workers 带来安全风险 **预防：**使用 CSS 选择器，或通过 page.evaluate() 配合 XPathEvaluator

解决方案：

// ❌ Don't use XPath directly (not supported)
// await page.$x('/html/body/div/h1')

// ✅ Use CSS selector
const heading = await page.$("div > h1");

// ✅ Or use XPath in page.evaluate()
const innerHtml = await page.evaluate(() => {
  return new XPathEvaluator()
    .createExpression("/html/body/div/h1")
    .evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE)
    .singleNodeValue.innerHTML;
});

---

问题 #2：未传递浏览器绑定 ⚠️

错误：“Cannot read properties of undefined (reading 'fetch')” 来源： https://developers.cloudflare.com/browser-rendering/faq/#cannot-read-properties-of-undefined-reading-fetch **发生原因：**调用 puppeteer.launch() 时未传递浏览器绑定 **预防方法：**始终将 env.MYBROWSER 传递给 launch

解决方案：

// ❌ Missing browser binding
const browser = await puppeteer.launch(); // Error!

// ✅ Pass binding
const browser = await puppeteer.launch(env.MYBROWSER);

---

问题 #3：浏览器超时（60 秒）⚠️

**错误：**浏览器在 60 秒后意外关闭 来源： https://developers.cloudflare.com/browser-rendering/platform/limits/#note-on-browser-timeout **发生原因：**默认超时时间为 60 秒无活动 **预防方法：**使用 keep_alive 选项，将超时时间延长至最多 10 分钟

解决方案：

// Extend timeout to 5 minutes for long-running tasks
const browser = await puppeteer.launch(env.MYBROWSER, {
  keep_alive: 300000 // 5 minutes = 300,000 ms
});

**注意：**如果在指定时长内没有 devtools 命令，浏览器就会关闭。

---

其他问题（4-6）

加载 references/common-errors.md，查看完整的错误目录，包括：

• 问题 #4：并发限制和速率限制
• 问题 #5：本地开发请求大小限制
• 问题 #6：机器人防护和 WAF 绕过策略

此外，还包含页面崩溃、身份验证问题、资源加载错误的解决方案，以及调试策略。

---

生产环境检查清单

部署前的关键事项：

• ✅ 已配置浏览器绑定和 nodejs_compat 标志
• ✅ 使用 try-finally 进行错误处理和清理
• ✅ 速率限制检查和重试逻辑
• ✅ 通过重复使用会话提升性能
• ✅ 使用 KV 缓存重复操作
• ✅ 输入验证（防止 SSRF）
• ✅ 监控面板：https://dash.cloudflare.com

加载 references/patterns.md，查看包含完整错误处理、监控和安全模式的生产就绪模板。

---

依赖项

必需项：@cloudflare/[email protected]、[email protected]、@cloudflare/[email protected] 相关技能：cloudflare-worker-base（Worker 设置）、cloudflare-kv（缓存）、cloudflare-workers-ai（AI 抓取）

---

官方文档

• Browser Rendering 文档：https://developers.cloudflare.com/browser-rendering/
• Puppeteer API：https://pptr.dev/api/
• Playwright API：https://playwright.dev/docs/api/class-playwright
• Cloudflare Puppeteer 分支：https://github.com/cloudflare/puppeteer
• Cloudflare Playwright 分支：https://github.com/cloudflare/playwright
• 定价：https://developers.cloudflare.com/browser-rendering/platform/pricing/
• 限制：https://developers.cloudflare.com/browser-rendering/platform/limits/

---

软件包版本（已于 2025-11-27 验证）

{
  "dependencies": {
    "@cloudflare/puppeteer": "^1.0.4"
  },
  "devDependencies": {
    "@cloudflare/workers-types": "^4.20260408.0",
    "wrangler": "^4.81.0"
  }
}

替代方案（Playwright）：

{
  "dependencies": {
    "@cloudflare/playwright": "^1.0.0"
  }
}

---

故障排除

问题：“Cannot read properties of undefined (reading 'fetch')”

**解决方案：**将浏览器绑定传递给 puppeteer.launch()：

const browser = await puppeteer.launch(env.MYBROWSER); // Not just puppeteer.launch()

问题：XPath 选择器无法使用

**解决方案：**使用 CSS 选择器，或通过 XPathEvaluator 配合 page.evaluate() 使用（参见问题 #1）

问题：浏览器在 60 秒后关闭

**解决方案：**使用 keep_alive 延长超时时间：

const browser = await puppeteer.launch(env.MYBROWSER, { keep_alive: 300000 });

问题：达到速率限制

**解决方案：**重复使用会话、使用标签页，并在启动前检查限制（参见问题 #4）

问题：本地开发请求 > 1MB 时失败

**解决方案：**在 wrangler.jsonc 中启用远程绑定：

{ "browser": { "binding": "MYBROWSER", "remote": true } }

问题：网站将请求拦截为机器人流量

**解决方案：**无法绕过。如果这是你自己的区域，请创建 WAF 跳过规则（参见问题 #6）

---

有疑问？遇到问题？

1. 查看 references/common-errors.md，了解详细解决方案
2. 查看 references/session-management.md，了解性能优化
3. 确认已在 wrangler.jsonc 中配置浏览器绑定
4. 查看官方文档：https://developers.cloudflare.com/browser-rendering/
5. 确认已启用 nodejs_compat 兼容性标志