⚡

Cloudflare浏览器渲染技能 cloudflare-browser-rendering

这个技能是关于使用Cloudflare Browser Rendering服务进行浏览器自动化。它支持通过Puppeteer或Playwright工具在Cloudflare Workers上实现屏幕截图、PDF生成、网页抓取、自动化测试等任务。适用于开发者和企业，用于构建高效、可扩展的云原生应用。关键词：浏览器渲染, Cloudflare, Puppeteer, Playwright, 屏幕截图, PDF生成, 网页抓取, 浏览器自动化, Serverless, 无头浏览器, 网络爬虫

Serverless 0 次安装 0 次浏览 更新于 3/8/2026

名称: cloudflare-browser-rendering 描述: 使用 Puppeteer/Playwright 的 Cloudflare 浏览器渲染。用于屏幕截图、PDF生成、网页抓取，或遇到渲染错误、超时问题、内存超限。

关键词: 浏览器渲染 cloudflare, @cloudflare/puppeteer, @cloudflare/playwright, puppeteer workers, playwright workers, 屏幕截图 cloudflare, pdf 生成 workers, 网页抓取 cloudflare, 无头 chrome workers, 浏览器自动化, puppeteer.launch, playwright.chromium.launch, 浏览器绑定, 会话管理, puppeteer.sessions, puppeteer.connect, browser.close, browser.disconnect, XPath 不支持, 浏览器超时, 并发限制, keep_alive, page.screenshot, page.pdf, page.goto, page.evaluate, 隐私模式上下文, 会话重用, 批量抓取, 爬取网站 许可证: MIT 元数据: 版本: “1.0.0” 最后验证: “2025-11-27” puppeteer_version: “1.0.4” playwright_version: “1.0.0” workers_types_version: “4.20251125.0” wrangler_version: “4.50.0” production_tested: true errors_prevented: 6 references_included: 6

Cloudflare 浏览器渲染 - 完整参考

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

状态: 生产就绪 ✅ 最后更新: 2025-11-25 依赖项: cloudflare-worker-base（用于 Worker 设置） 最新版本: @cloudflare/puppeteer@1.0.4, @cloudflare/playwright@1.0.0, wrangler@4.50.0, @cloudflare/workers-types@4.20251125.0

目录

  1. 快速开始（5分钟）
  2. 浏览器渲染概述
  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";

    // 启动浏览器
    const browser = await puppeteer.launch(env.MYBROWSER);
    const page = await browser.newPage();

    // 导航并捕获
    await page.goto(url);
    const screenshot = await page.screenshot();

    // 清理
    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

浏览器渲染概述

什么是浏览器渲染？

Cloudflare Browser Rendering 提供在 Cloudflare 全球网络上运行的无头 Chromium 浏览器。使用熟悉的工具如 Puppeteer 和 Playwright 来自动化浏览器任务：

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

两种集成方法

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

此技能涵盖 Workers Bindings（高级方法，具有完整的 Puppeteer/Playwright API）。

Puppeteer 对比 Playwright

功能 Puppeteer Playwright
API 熟悉度 最流行 增长采用
包 @cloudflare/puppeteer@1.0.4 @cloudflare/playwright@1.0.0
会话管理 ✅ 高级 API ⚠️ 基本
浏览器支持 仅 Chromium 仅 Chromium（Firefox/Safari 尚未支持）
最适合 屏幕截图、PDF、抓取 测试、前端自动化

推荐: 对于大多数用例，使用 Puppeteer。如果已经用于测试，Playwright 是理想选择。

Puppeteer API 参考

浏览器自动化的核心类:

  1. 核心函数 - launch(), connect(), sessions(), history(), limits()
  2. Browser API - newPage(), sessionId(), close(), disconnect(), createBrowserContext()
  3. Page 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 个记录的问题。前三关键错误详细如下：

问题 #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

解决方案:

// ❌ 不要直接使用 XPath（不支持）
// await page.$x('/html/body/div/h1')

// ✅ 使用 CSS 选择器
const heading = await page.$("div > h1");

// ✅ 或在 page.evaluate() 中使用 XPath
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

解决方案:

// ❌ 缺少浏览器绑定
const browser = await puppeteer.launch(); // 错误！

// ✅ 传递绑定
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 分钟

解决方案:

// 为长时间运行任务延长超时至 5 分钟
const browser = await puppeteer.launch(env.MYBROWSER, {
  keep_alive: 300000 // 5 分钟 = 300,000 毫秒
});

注意: 如果指定时间内没有开发工具命令，浏览器将关闭。

额外问题（4-6）

加载 references/common-errors.md 以获取完整的错误目录包括:

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

以及页面崩溃、认证问题、资源加载错误和调试策略的解决方案。

生产检查表

部署前关键项:

  • ✅ 浏览器绑定 + nodejs_compat 标志已配置
  • ✅ 错误处理，带 try-finally 清理
  • ✅ 速率限制检查和重试逻辑
  • ✅ 会话重用以优化性能
  • ✅ KV 缓存用于重复操作
  • ✅ 输入验证（防止 SSRF）
  • ✅ 监控仪表板在 https://dash.cloudflare.com

对于生产就绪的模板（包括完整错误处理、监控和安全模式），加载 references/patterns.md。

依赖项

必需: @cloudflare/puppeteer@1.0.4, wrangler@4.50.0, @cloudflare/workers-types@4.20251125.0 相关技能: cloudflare-worker-base（Worker 设置）, cloudflare-kv（缓存）, cloudflare-workers-ai（AI 抓取）

官方文档

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

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

替代方案（Playwright）:

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

故障排除

问题: “Cannot read properties of undefined (reading ‘fetch’)”

解决方案: 传递浏览器绑定到 puppeteer.launch():

const browser = await puppeteer.launch(env.MYBROWSER); // 不只是 puppeteer.launch()

问题: XPath 选择器不工作

解决方案: 使用 CSS 选择器或 page.evaluate() 与 XPathEvaluator（见问题 #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 兼容性标志已启用