Cloudflare Browser Rendering 浏览器自动化指南：Puppeteer与Playwright API完整参考

cloudflare-browser-rendering by jezweb/claude-skills

341 周安装量

650 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jezweb/claude-skills --skill cloudflare-browser-rendering

自动化云服务测试

🇨🇳中文介绍

Cloudflare Browser Rendering - 完整参考

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

状态 : 生产就绪 ✅ 最后更新 : 2026-01-21 依赖项 : cloudflare-worker-base (用于 Worker 设置) 最新版本 : @cloudflare/puppeteer@1.0.4, @cloudflare/playwright@1.1.0, wrangler@4.59.3

近期更新 (2025) :

2025年9月 : Playwright v1.55 正式发布，支持 Stagehand 框架 (Workers AI)，/links 端点新增 excludeExternalLinks 参数
2025年8月 : 计费功能正式发布 (8月20日)，本地开发支持 /sessions 端点，新增 X-Browser-Ms-Used 请求头
2025年7月 : Playwright v1.54.1 + MCP v0.0.30，支持 Playwright 本地开发 (wrangler@4.26.0+)，同步 Puppeteer v22.13.1，/content 端点返回标题，/json 端点新增 custom_ai 参数，/screenshot 端点视口默认值改为 1920x1080
2025年6月 : 自动包含 Web Bot 认证请求头
2025年4月 : 发布 Playwright 支持，引入免费套餐

快速开始 (5分钟)

1. 添加浏览器绑定

wrangler.jsonc:

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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" }
    });
  }
};

npx wrangler deploy

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

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

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/puppeteer@1.0.4`	`@cloudflare/playwright@1.0.0`
会话管理	✅ 高级 API	⚠️ 基础
浏览器支持	仅 Chromium	仅 Chromium (Firefox/Safari 尚未支持)
最适合	截图、PDF、抓取	测试、前端自动化

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

Puppeteer API 参考

核心 API (完整参考: https://pptr.dev/api/):

puppeteer.launch(env.MYBROWSER, options?) - 启动新浏览器 (关键: 必须传递绑定)
puppeteer.connect(env.MYBROWSER, sessionId) - 连接到现有会话
puppeteer.sessions(env.MYBROWSER) - 列出运行中的会话
puppeteer.history(env.MYBROWSER) - 列出最近会话 (打开 + 已关闭)
puppeteer.limits(env.MYBROWSER) - 检查账户限制

浏览器方法:

browser.newPage() - 创建新标签页 (优于启动新浏览器)
browser.sessionId() - 获取会话 ID 以供复用
browser.close() - 终止会话
browser.disconnect() - 保持会话活跃以供复用
browser.createBrowserContext() - 隔离的无痕上下文 (独立的 cookies/缓存)

page.goto(url, { waitUntil, timeout }) - 导航 (对动态内容使用 "networkidle0")
page.screenshot({ fullPage, type, quality, clip }) - 捕获图像
page.pdf({ format, printBackground, margin }) - 生成 PDF
page.evaluate(() => ...) - 在浏览器中执行 JS (数据提取，XPath 变通方案)
page.content() / page.setContent(html) - 获取/设置 HTML
page.waitForSelector(selector) - 等待元素
page.type(selector, text) / page.click(selector) - 表单交互

// 必须传递绑定
const browser = await puppeteer.launch(env.MYBROWSER); // ✅
// const browser = await puppeteer.launch(); // ❌ 错误！

// 会话复用以提高性能
const sessions = await puppeteer.sessions(env.MYBROWSER);
const freeSessions = sessions.filter(s => !s.connectionId);
if (freeSessions.length > 0) {
  browser = await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId);
}

// 保持会话活跃
await browser.disconnect(); // 不要关闭

// XPath 变通方案 (不直接支持)
const data = await page.evaluate(() => {
  return new XPathEvaluator()
    .createExpression("/html/body/div/h1")
    .evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE)
    .singleNodeValue.innerHTML;
});

Playwright API 参考

状态 : 正式发布 (2025年9月) - 支持 Playwright v1.55、MCP v0.0.30、本地开发支持 (wrangler@4.26.0+)

npm install @cloudflare/playwright

配置要求 (2025 年更新):

{
  "compatibility_flags": ["nodejs_compat"],
  "compatibility_date": "2025-09-15"  // Playwright v1.55 必需
}

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

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();

Puppeteer 与 Playwright 对比:

导入 : puppeteer 对比从 "@cloudflare/playwright" 导入 { chromium }
会话 API : Puppeteer 具有高级会话管理 (sessions/history/limits)，Playwright 为基本
自动等待 : Playwright 具有内置自动等待，Puppeteer 需要手动 waitForSelector()
MCP 支持 : Playwright MCP v0.0.30 (2025年7月)，Playwright MCP 服务器可用
最新版本 : 支持 Playwright v1.57 (2026年1月更新)

推荐 : 对于会话复用模式使用 Puppeteer。如果迁移现有测试或需要 MCP 集成，则使用 Playwright。

为什么 : 启动新浏览器速度慢且消耗并发限制。复用会话以获得更快的响应、更低的并发使用率、更好的资源利用率。

会话复用模式 (关键)

async function getBrowser(env: Env): Promise<Browser> {
  const sessions = await puppeteer.sessions(env.MYBROWSER);
  const freeSessions = sessions.filter(s => !s.connectionId);

  if (freeSessions.length > 0) {
    try {
      return await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId);
    } catch (e) {
      console.log("Failed to connect, launching new browser");
    }
  }

  return await puppeteer.launch(env.MYBROWSER);
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const browser = await getBrowser(env);

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

      await browser.disconnect(); // ✅ 保持活跃以供复用

      return new Response(screenshot, {
        headers: { "content-type": "image/png" }
      });
    } catch (error) {
      await browser.close(); // ❌ 出错时关闭
      throw error;
    }
  }
};

✅ browser.disconnect() - 保持会话活跃以供复用
❌ browser.close() - 仅在出错或真正完成时使用
✅ 始终处理连接失败

浏览器上下文 (Cookie/缓存隔离)

使用 browser.createBrowserContext() 来共享浏览器但隔离 cookies/缓存:

const browser = await puppeteer.launch(env.MYBROWSER);
const context1 = await browser.createBrowserContext(); // 用户 1
const context2 = await browser.createBrowserContext(); // 用户 2

const page1 = await context1.newPage();
const page2 = await context2.newPage();
// 每个上下文独立的 cookies/缓存

❌ 错误做法 : 为 10 个 URL 启动 10 个浏览器 (浪费并发) ✅ 正确做法 : 1 个浏览器，通过 Promise.all() + browser.newPage() 创建 10 个标签页

const browser = await puppeteer.launch(env.MYBROWSER);
const results = await Promise.all(
  urls.map(async (url) => {
    const page = await browser.newPage();
    await page.goto(url);
    const data = await page.evaluate(() => ({ title: document.title }));
    await page.close();
    return { url, data };
  })
);
await browser.close();

带 KV 缓存的截图

缓存截图以减少浏览器使用并提高性能:

interface Env {
  MYBROWSER: Fetcher;
  CACHE: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { searchParams } = new URL(request.url);
    const url = searchParams.get("url");
    if (!url) return new Response("Missing ?url parameter", { status: 400 });

    const normalizedUrl = new URL(url).toString();

    // 首先检查缓存
    let screenshot = await env.CACHE.get(normalizedUrl, { type: "arrayBuffer" });

    if (!screenshot) {
      const browser = await puppeteer.launch(env.MYBROWSER);
      const page = await browser.newPage();
      await page.goto(normalizedUrl);
      screenshot = await page.screenshot();
      await browser.close();

      // 缓存 24 小时
      await env.CACHE.put(normalizedUrl, screenshot, { expirationTtl: 60 * 60 * 24 });
    }

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

结合 Browser Rendering 与 Workers AI 进行结构化数据提取:

interface Env {
  MYBROWSER: Fetcher;
  AI: Ai;
}

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

    // 抓取页面内容
    const browser = await puppeteer.launch(env.MYBROWSER);
    const page = await browser.newPage();
    await page.goto(url!, { waitUntil: "networkidle0" });
    const bodyContent = await page.$eval("body", el => el.innerHTML);
    await browser.close();

    // 使用 AI 提取结构化数据
    const response = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [{
        role: "user",
        content: `Extract product info as JSON from this HTML. Include: name, price, description.\n\nHTML:\n${bodyContent.slice(0, 4000)}`
      }]
    });

    return Response.json({ url, product: JSON.parse(response.response) });
  }
};

其他常用模式 : PDF 生成 (page.pdf())、结构化抓取 (page.evaluate())、表单自动化 (page.type() + page.click())。参见捆绑的 templates/ 目录。

计费正式发布 : 2025年8月20日

免费套餐 : 10 分钟/天，3 个并发，3 次启动/分钟，60 秒超时 付费套餐 : 包含 10 小时/月 (之后 $0.09/小时)，30 个并发 (之后 $2.00/浏览器)，30 次启动/分钟，60 秒-10 分钟超时

并发计算 : 每日峰值使用量的月平均值 (例如，35 个浏览器平均值 = (35 - 30 包含) × $2.00 = $10.00/月)

速率限制 : 使用固定的每秒填充速率强制执行 (不适用于突发)。30 次请求/分钟 = 每 2 秒 1 次请求。即使配额未使用，您也无法一次性发送所有 30 个请求。在启动前检查 puppeteer.limits(env.MYBROWSER):

const limits = await puppeteer.limits(env.MYBROWSER);
if (limits.allowedBrowserAcquisitions === 0) {
  const delay = limits.timeUntilNextAllowedBrowserAcquisition || 1000;
  await new Promise(resolve => setTimeout(resolve, delay));
}

本技能预防 8 个已记录的问题 :

问题 #1: 不支持 XPath 选择器

错误: "XPath selector not supported" 或选择器失败 来源: 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: 未传递浏览器绑定 (Fetcher 类型混淆)

错误: "Cannot read properties of undefined (reading 'fetch')" 或 "RPC receiver does not implement the method 'launch'" 来源: GitHub Issue #10772, https://developers.cloudflare.com/browser-rendering/faq/#cannot-read-properties-of-undefined-reading-fetch 发生原因: 调用 puppeteer.launch() 时未传递浏览器绑定，或尝试直接调用 env.MYBROWSER.launch()。浏览器绑定是一个 Fetcher (REST API 包装器)，而不是浏览器实例。 预防: 始终将 env.MYBROWSER 传递给 puppeteer.launch() 或 chromium.launch() 包装器

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

// ❌ 错误 - 尝试直接在 Fetcher 上调用 launch()
const browser = await env.MYBROWSER.launch(); // "RPC receiver does not implement the method 'launch'"

// ✅ 将绑定传递给 Puppeteer/Playwright 包装器
const browser = await puppeteer.launch(env.MYBROWSER);
// 或对于 Playwright:
const browser = await chromium.launch(env.MYBROWSER);

TypeScript 类型解释:

interface Env {
  MYBROWSER: Fetcher; // 它是一个 Fetcher，不是 Browser！
}

问题 #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 毫秒
});

注意: 如果在指定持续时间内没有 devtools 命令，浏览器将关闭。

问题 #4: 达到并发限制

错误: "Rate limit exceeded" 或新浏览器启动失败 来源: https://developers.cloudflare.com/browser-rendering/platform/limits/, Changelog 2025-09-25 发生原因: 超出并发浏览器限制 (截至 2025年9月，免费 3 个，付费 30 个) 预防: 复用会话，使用标签页而非多个浏览器，启动前检查限制，将请求限制在每秒速率内

// 1. 启动前检查限制
const limits = await puppeteer.limits(env.MYBROWSER);
if (limits.allowedBrowserAcquisitions === 0) {
  return new Response("Concurrency limit reached", { status: 429 });
}

// 2. 复用会话
const sessions = await puppeteer.sessions(env.MYBROWSER);
const freeSessions = sessions.filter(s => !s.connectionId);
if (freeSessions.length > 0) {
  const browser = await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId);
}

// 3. 使用标签页而非多个浏览器
const browser = await puppeteer.launch(env.MYBROWSER);
const page1 = await browser.newPage();
const page2 = await browser.newPage(); // 同一浏览器，不同标签页

问题 #5: 本地开发请求大小限制

错误: 大于 1MB 的请求在 wrangler dev 中失败 来源: https://developers.cloudflare.com/browser-rendering/faq/#does-local-development-support-all-browser-rendering-features 发生原因: 本地开发限制 预防: 在本地开发中使用浏览器绑定的 remote: true

// 用于本地开发的 wrangler.jsonc
{
  "browser": {
    "binding": "MYBROWSER",
    "remote": true  // 在开发期间使用真实的无头浏览器
  }
}

问题 #6: 始终触发机器人防护

错误: 网站将请求阻止为机器人流量 来源: https://developers.cloudflare.com/browser-rendering/faq/#will-browser-rendering-bypass-cloudflares-bot-protection 发生原因: Browser Rendering 请求始终被识别为机器人 预防: 无法绕过；如果抓取您自己的区域，请创建 WAF 跳过规则 (需要企业计划以使用 Bot Management)

// ❌ 无法绕过机器人防护
// 请求将始终被识别为机器人

// ✅ 如果抓取您自己的 Cloudflare 区域 (仅限企业计划):
// 1. 转到 Security > WAF > Custom rules
// 2. 使用自定义请求头创建跳过规则:
//    请求头: X-Custom-Auth
//    值: your-secret-token
// 3. 在抓取请求中传递该请求头

await page.setExtraHTTPHeaders({
  'X-Custom-Auth': 'your-secret-token'
});

// 注意: 自动包含以下请求头:
// - cf-biso-request-id
// - cf-biso-devtools

重要: 免费/专业/商业计划即使在自己的站点上也无法绕过机器人检测。需要具有 Bot Management 的企业计划才能进行 WAF 允许列表设置。

问题 #7: page.evaluate() 函数名注入 (__name 错误)

错误: ReferenceError: __name is not defined 来源: GitHub Issue #7107 发生原因: esbuild 压缩 (wrangler 3.80.1+) 在包含嵌套函数声明的箭头函数中注入 __name() 辅助调用。这些在浏览器上下文中运行，而辅助函数不存在。 预防: 保持 page.evaluate() 函数简单 - 避免嵌套函数声明 适用于: wrangler 3.80.1 - 3.83.0 (在 3.83.0+ 中修复)

// ❌ 避免嵌套函数声明
const data = await page.evaluate(async () => {
  function toNumber(str: string | undefined): number | undefined {
    const num = typeof str === 'string' ? str.replaceAll('.', '').replaceAll(',', '.').match(/[+-]?([0-9]*[.])?[0-9]+/) : false;
    if (num) {
      return Number(num[0]);
    } else {
      return undefined;
    }
  }
  return toNumber('123.456');
});
// 错误: ReferenceError: __name is not defined

// ✅ 内联逻辑而不使用嵌套函数
const data = await page.evaluate(async () => {
  const str = '123.456';
  const num = typeof str === 'string' ? str.replaceAll('.', '').replaceAll(',', '.').match(/[+-]?([0-9]*[.])?[0-9]+/) : false;
  return num ? Number(num[0]) : undefined;
});

// ✅ 或更新到 wrangler 3.83.0+
// npm install wrangler@latest

注意: 这也影响具有复杂回调的 page.waitForSelector()。已在 wrangler 3.83.0+ (2024年11月) 中修复。

问题 #8: waitForSelector() 超时行为已更改

错误: 依赖无限等待的代码现在会超时 来源: Changelog 2026-01-07 发生原因: waitForSelector() 以前在未找到选择器时不会超时 (无限挂起)。现已修复以正确遵守超时值。 预防: 始终设置显式超时并处理超时错误 适用于: 所有在 2026年1月之前编写并依赖无限等待的代码

// ❌ 旧行为 - 如果未找到选择器将永远挂起
await page.waitForSelector('#dynamic-element');

// ✅ 新行为 - 正确超时 (设置显式超时)
try {
  await page.waitForSelector('#dynamic-element', { timeout: 5000 });
} catch (error) {
  if (error.name === 'TimeoutError') {
    console.log('Element not found within 5 seconds');
    // 优雅处理缺失元素
  } else {
    throw error;
  }
}

// ✅ 对加载缓慢的元素使用更长的超时
await page.waitForSelector('#slow-element', { timeout: 30000 }); // 30 秒

注意: 这是一个破坏性修复 (行为变更)。依赖无限等待的代码现在将超时并抛出错误。始终优雅地处理 TimeoutError。

生产环境检查清单

将 Browser Rendering Workers 部署到生产环境前:

浏览器绑定已配置 在 wrangler.jsonc 中
已启用 nodejs_compat 标志 (Browser Rendering 必需)
设置了保持活跃超时 如果任务耗时 > 60 秒
已启用远程绑定 用于本地开发 (如果需要)

已实现重试逻辑 用于速率限制
超时处理 用于 page.goto()
浏览器清理 在 try-finally 块中
并发限制检查 在启动浏览器前
优雅降级 当浏览器不可用时

已实现会话复用 用于高流量路由
使用多个标签页 而非多个浏览器
无痕上下文 用于会话隔离
KV 缓存 用于重复截图/PDF
批量操作 以最大化浏览器利用率

记录浏览器会话 ID 用于调试
跟踪浏览器持续时间 用于计费估算
监控并发使用情况 使用 puppeteer.limits()
速率限制错误告警
仪表板监控 地址: https://dash.cloudflare.com/?to=/:account/workers/browser-rendering

输入验证 用于 URL (防止 SSRF)
超时限制 防止滥用
速率限制 在公共端点上
身份验证 用于敏感抓取端点
WAF 规则 如果抓取您自己的区域

测试截图捕获 使用各种页面大小
测试 PDF 生成 使用自定义 HTML
测试抓取 使用动态内容 (networkidle0)
测试错误场景 (无效 URL、超时)
负载测试 并发限制

错误处理最佳实践

生产模式 - 使用 try-catch 进行适当清理:

async function withBrowser<T>(env: Env, fn: (browser: Browser) => Promise<T>): Promise<T> {
  let browser: Browser | null = null;

  try {
    // 1. 启动前检查限制
    const limits = await puppeteer.limits(env.MYBROWSER);
    if (limits.allowedBrowserAcquisitions === 0) {
      throw new Error("Rate limit reached");
    }

    // 2. 首先尝试会话复用
    const sessions = await puppeteer.sessions(env.MYBROWSER);
    const freeSessions = sessions.filter(s => !s.connectionId);
    browser = freeSessions.length > 0
      ? await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId)
      : await puppeteer.launch(env.MYBROWSER);

    // 3. 执行用户函数
    const result = await fn(browser);

    // 4. 断开连接 (保持活跃)
    await browser.disconnect();
    return result;
  } catch (error) {
    // 5. 出错时关闭
    if (browser) await browser.close();
    throw error;
  }
}

关键原则 : 检查限制 → 复用会话 → 执行 → 成功时断开连接，出错时关闭

用于常见模式的即用型代码模板:

basic-screenshot.ts - 最小截图示例
screenshot-with-kv-cache.ts - 带 KV 缓存的截图
pdf-generation.ts - 从 HTML 或 URL 生成 PDF
web-scraper-basic.ts - 基本网页抓取模式
web-scraper-batch.ts - 批量抓取多个 URL
session-reuse.ts - 会话复用以提高性能
ai-enhanced-scraper.ts - 使用 Workers AI 的抓取
playwright-example.ts - Playwright 替代示例
wrangler-browser-config.jsonc - 浏览器绑定配置

# 复制模板到您的项目
cp ~/.claude/skills/cloudflare-browser-rendering/templates/basic-screenshot.ts src/index.ts

参考 (references/)

session-management.md - 完整的会话复用指南
pricing-and-limits.md - 详细的定价明细
common-errors.md - 所有已知问题及解决方案
puppeteer-vs-playwright.md - 功能对比和迁移

何时加载: 在实现高级模式或调试特定问题时参考。

@cloudflare/puppeteer@1.0.4 - 用于 Workers 的 Puppeteer
wrangler@4.43.0+ - Cloudflare CLI

@cloudflare/playwright@1.0.0 - 用于 Workers 的 Playwright (替代方案)
@cloudflare/workers-types@4.20251014.0+ - TypeScript 类型

cloudflare-worker-base - 使用 Hono 的 Worker 设置
cloudflare-kv - 用于截图的 KV 缓存
cloudflare-r2 - 用于生成文件的 R2 存储
cloudflare-workers-ai - AI 增强的抓取

包版本 (已验证 2026-01-21)

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

替代方案 (Playwright):

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

注意: Playwright v1.1.0 包含对 Playwright v1.57 (2026年1月) 的支持。Wrangler 3.83.0+ 修复了 page.evaluate() __name 注入错误。

问题: "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)

🇺🇸English

Cloudflare Browser Rendering - Complete Reference

Production-ready knowledge domain for building browser automation workflows with Cloudflare Browser Rendering.

Status : Production Ready ✅ Last Updated : 2026-01-21 Dependencies : cloudflare-worker-base (for Worker setup) Latest Versions : @cloudflare/puppeteer@1.0.4, @cloudflare/playwright@1.1.0, wrangler@4.59.3

Recent Updates (2025) :

Sept 2025 : Playwright v1.55 GA, Stagehand framework support (Workers AI), /links excludeExternalLinks param
Aug 2025 : Billing GA (Aug 20), /sessions endpoint in local dev, X-Browser-Ms-Used header
July 2025 : Playwright v1.54.1 + MCP v0.0.30, Playwright local dev support (wrangler@4.26.0+), Puppeteer v22.13.1 sync, /content returns title, /json custom_ai param, /screenshot viewport 1920x1080 default
June 2025 : Web Bot Auth headers auto-included
April 2025 : Playwright support launched, free tier introduced

Quick Start (5 minutes)
Browser Rendering Overview
Puppeteer API Reference
Playwright API Reference
Session Management
Common Patterns
Pricing & Limits
Known Issues Prevention
Production Checklist

Quick Start (5 minutes)

1. Add Browser Binding

wrangler.jsonc:

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

Why nodejs_compat? Browser Rendering requires Node.js APIs and polyfills.

2. Install Puppeteer

npm install @cloudflare/puppeteer

3. Take Your First Screenshot

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. Deploy

npx wrangler deploy

Test at: https://your-worker.workers.dev/?url=https://example.com

CRITICAL:

Always pass env.MYBROWSER to puppeteer.launch() (not undefined)
Always call browser.close() when done (or use browser.disconnect() for session reuse)
Use nodejs_compat compatibility flag

Browser Rendering Overview

What is Browser Rendering?

Cloudflare Browser Rendering provides headless Chromium browsers running on Cloudflare's global network. Use familiar tools like Puppeteer and Playwright to automate browser tasks:

Screenshots - Capture visual snapshots of web pages
PDF Generation - Convert HTML/URLs to PDFs
Web Scraping - Extract content from dynamic websites
Testing - Automate frontend tests
Crawling - Navigate multi-page workflows

Two Integration Methods

Method	Best For	Complexity
Workers Bindings	Complex automation, custom workflows, session management	Advanced
REST API	Simple screenshot/PDF tasks	Simple

This skill covers Workers Bindings (the advanced method with full Puppeteer/Playwright APIs).

Puppeteer vs Playwright

Feature	Puppeteer	Playwright
API Familiarity	Most popular	Growing adoption
Package	`@cloudflare/puppeteer@1.0.4`	`@cloudflare/playwright@1.0.0`
Session Management	✅ Advanced APIs	⚠️ Basic
Browser Support	Chromium only	Chromium only (Firefox/Safari not yet supported)
Best For	Screenshots, PDFs, scraping	Testing, frontend automation

Recommendation : Use Puppeteer for most use cases. Playwright is ideal if you're already using it for testing.

Puppeteer API Reference

Core APIs (complete reference: https://pptr.dev/api/):

Global Functions:

puppeteer.launch(env.MYBROWSER, options?) - Launch new browser (CRITICAL: must pass binding)
puppeteer.connect(env.MYBROWSER, sessionId) - Connect to existing session
puppeteer.sessions(env.MYBROWSER) - List running sessions
puppeteer.history(env.MYBROWSER) - List recent sessions (open + closed)
puppeteer.limits(env.MYBROWSER) - Check account limits

Browser Methods:

browser.newPage() - Create new tab (preferred over launching new browsers)
browser.sessionId() - Get session ID for reuse
browser.close() - Terminate session
browser.disconnect() - Keep session alive for reuse
browser.createBrowserContext() - Isolated incognito context (separate cookies/cache)

Page Methods:

page.goto(url, { waitUntil, timeout }) - Navigate (use "networkidle0" for dynamic content)
page.screenshot({ fullPage, type, quality, clip }) - Capture image
page.pdf({ format, printBackground, margin }) - Generate PDF
page.evaluate(() => ...) - Execute JS in browser (data extraction, XPath workaround)
page.content() / page.setContent(html) - Get/set HTML
page.waitForSelector(selector) - Wait for element
page.type(selector, text) / - Form interaction

Critical Patterns:

// Must pass binding
const browser = await puppeteer.launch(env.MYBROWSER); // ✅
// const browser = await puppeteer.launch(); // ❌ Error!

// Session reuse for performance
const sessions = await puppeteer.sessions(env.MYBROWSER);
const freeSessions = sessions.filter(s => !s.connectionId);
if (freeSessions.length > 0) {
  browser = await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId);
}

// Keep session alive
await browser.disconnect(); // Don't close

// XPath workaround (not directly supported)
const data = await page.evaluate(() => {
  return new XPathEvaluator()
    .createExpression("/html/body/div/h1")
    .evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE)
    .singleNodeValue.innerHTML;
});

Playwright API Reference

Status : GA (Sept 2025) - Playwright v1.55, MCP v0.0.30 support, local dev support (wrangler@4.26.0+)

Installation:

npm install @cloudflare/playwright

Configuration Requirements (2025 Update):

{
  "compatibility_flags": ["nodejs_compat"],
  "compatibility_date": "2025-09-15"  // Required for Playwright v1.55
}

Basic Usage:

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

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();

Puppeteer vs Playwright:

Import : puppeteer vs { chromium } from "@cloudflare/playwright"
Session API : Puppeteer has advanced session management (sessions/history/limits), Playwright basic
Auto-waiting : Playwright has built-in auto-waiting, Puppeteer requires manual waitForSelector()
MCP Support : Playwright MCP v0.0.30 (July 2025), Playwright MCP server available
Latest Version : Playwright v1.57 support (Jan 2026 update)

Recommendation : Use Puppeteer for session reuse patterns. Use Playwright if migrating existing tests or need MCP integration.

Official Docs : https://developers.cloudflare.com/browser-rendering/playwright/

Session Management

Why : Launching new browsers is slow and consumes concurrency limits. Reuse sessions for faster response, lower concurrency usage, better resource utilization.

Session Reuse Pattern (Critical)

async function getBrowser(env: Env): Promise<Browser> {
  const sessions = await puppeteer.sessions(env.MYBROWSER);
  const freeSessions = sessions.filter(s => !s.connectionId);

  if (freeSessions.length > 0) {
    try {
      return await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId);
    } catch (e) {
      console.log("Failed to connect, launching new browser");
    }
  }

  return await puppeteer.launch(env.MYBROWSER);
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const browser = await getBrowser(env);

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

      await browser.disconnect(); // ✅ Keep alive for reuse

      return new Response(screenshot, {
        headers: { "content-type": "image/png" }
      });
    } catch (error) {
      await browser.close(); // ❌ Close on error
      throw error;
    }
  }
};

Key Rules:

✅ browser.disconnect() - Keep session alive for reuse
❌ browser.close() - Only on errors or when truly done
✅ Always handle connection failures

Browser Contexts (Cookie/Cache Isolation)

Use browser.createBrowserContext() to share browser but isolate cookies/cache:

const browser = await puppeteer.launch(env.MYBROWSER);
const context1 = await browser.createBrowserContext(); // User 1
const context2 = await browser.createBrowserContext(); // User 2

const page1 = await context1.newPage();
const page2 = await context2.newPage();
// Separate cookies/cache per context

Multiple Tabs Pattern

❌ Bad : Launch 10 browsers for 10 URLs (wastes concurrency) ✅ Good : 1 browser, 10 tabs via Promise.all() + browser.newPage()

const browser = await puppeteer.launch(env.MYBROWSER);
const results = await Promise.all(
  urls.map(async (url) => {
    const page = await browser.newPage();
    await page.goto(url);
    const data = await page.evaluate(() => ({ title: document.title }));
    await page.close();
    return { url, data };
  })
);
await browser.close();

Common Patterns

Screenshot with KV Caching

Cache screenshots to reduce browser usage and improve performance:

interface Env {
  MYBROWSER: Fetcher;
  CACHE: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { searchParams } = new URL(request.url);
    const url = searchParams.get("url");
    if (!url) return new Response("Missing ?url parameter", { status: 400 });

    const normalizedUrl = new URL(url).toString();

    // Check cache first
    let screenshot = await env.CACHE.get(normalizedUrl, { type: "arrayBuffer" });

    if (!screenshot) {
      const browser = await puppeteer.launch(env.MYBROWSER);
      const page = await browser.newPage();
      await page.goto(normalizedUrl);
      screenshot = await page.screenshot();
      await browser.close();

      // Cache for 24 hours
      await env.CACHE.put(normalizedUrl, screenshot, { expirationTtl: 60 * 60 * 24 });
    }

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

AI-Enhanced Scraping

Combine Browser Rendering with Workers AI for structured data extraction:

interface Env {
  MYBROWSER: Fetcher;
  AI: Ai;
}

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

    // Scrape page content
    const browser = await puppeteer.launch(env.MYBROWSER);
    const page = await browser.newPage();
    await page.goto(url!, { waitUntil: "networkidle0" });
    const bodyContent = await page.$eval("body", el => el.innerHTML);
    await browser.close();

    // Extract structured data with AI
    const response = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [{
        role: "user",
        content: `Extract product info as JSON from this HTML. Include: name, price, description.\n\nHTML:\n${bodyContent.slice(0, 4000)}`
      }]
    });

    return Response.json({ url, product: JSON.parse(response.response) });
  }
};

Other Common Patterns : PDF generation (page.pdf()), structured scraping (page.evaluate()), form automation (page.type() + page.click()). See bundled templates/ directory.

Pricing & Limits

Billing GA : August 20, 2025

Free Tier : 10 min/day, 3 concurrent, 3 launches/min, 60s timeout Paid Tier : 10 hrs/month included ($0.09/hr after), 30 concurrent ($2.00/browser after), 30 launches/min, 60s-10min timeout

Concurrency Calculation : Monthly average of daily peak usage (e.g., 35 browsers avg = (35 - 30 included) × $2.00 = $10.00/mo)

Rate Limiting : Enforced with a fixed per-second fill rate (NOT burst-friendly). 30 req/min = 1 req every 2 seconds. You CANNOT send all 30 requests at once, even if quota is unused. Check puppeteer.limits(env.MYBROWSER) before launching:

const limits = await puppeteer.limits(env.MYBROWSER);
if (limits.allowedBrowserAcquisitions === 0) {
  const delay = limits.timeUntilNextAllowedBrowserAcquisition || 1000;
  await new Promise(resolve => setTimeout(resolve, delay));
}

Known Issues Prevention

This skill prevents 8 documented issues :

Issue #1: XPath Selectors Not Supported

Error: "XPath selector not supported" or selector failures Source: https://developers.cloudflare.com/browser-rendering/faq/#why-cant-i-use-an-xpath-selector-when-using-browser-rendering-with-puppeteer Why It Happens: XPath poses a security risk to Workers Prevention: Use CSS selectors or page.evaluate() with XPathEvaluator

Solution:

// ❌ 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;
});

Issue #2: Browser Binding Not Passed (Fetcher Type Confusion)

Error: "Cannot read properties of undefined (reading 'fetch')" or "RPC receiver does not implement the method 'launch'" Source: GitHub Issue #10772, https://developers.cloudflare.com/browser-rendering/faq/#cannot-read-properties-of-undefined-reading-fetch Why It Happens: puppeteer.launch() called without browser binding, or trying to call env.MYBROWSER.launch() directly. The browser binding is a Fetcher (REST API wrapper), not a browser instance. Prevention: Always pass env.MYBROWSER to puppeteer.launch() or chromium.launch() wrapper

Solution:

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

// ❌ Wrong - trying to call launch() on Fetcher directly
const browser = await env.MYBROWSER.launch(); // "RPC receiver does not implement the method 'launch'"

// ✅ Pass binding to Puppeteer/Playwright wrapper
const browser = await puppeteer.launch(env.MYBROWSER);
// or for Playwright:
const browser = await chromium.launch(env.MYBROWSER);

TypeScript Type Explanation:

interface Env {
  MYBROWSER: Fetcher; // It's a Fetcher, not a Browser!
}

Issue #3: Browser Timeout (60 seconds)

Error: Browser closes unexpectedly after 60 seconds Source: https://developers.cloudflare.com/browser-rendering/platform/limits/#note-on-browser-timeout Why It Happens: Default timeout is 60 seconds of inactivity Prevention: Use keep_alive option to extend up to 10 minutes

Solution:

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

Note: Browser closes if no devtools commands for the specified duration.

Issue #4: Concurrency Limits Reached

Error: "Rate limit exceeded" or new browser launch fails Source: https://developers.cloudflare.com/browser-rendering/platform/limits/, Changelog 2025-09-25 Why It Happens: Exceeded concurrent browser limit (3 free, 30 paid as of Sept 2025) Prevention: Reuse sessions, use tabs instead of multiple browsers, check limits before launching, throttle requests to per-second rate

Solutions:

// 1. Check limits before launching
const limits = await puppeteer.limits(env.MYBROWSER);
if (limits.allowedBrowserAcquisitions === 0) {
  return new Response("Concurrency limit reached", { status: 429 });
}

// 2. Reuse sessions
const sessions = await puppeteer.sessions(env.MYBROWSER);
const freeSessions = sessions.filter(s => !s.connectionId);
if (freeSessions.length > 0) {
  const browser = await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId);
}

// 3. Use tabs instead of multiple browsers
const browser = await puppeteer.launch(env.MYBROWSER);
const page1 = await browser.newPage();
const page2 = await browser.newPage(); // Same browser, different tabs

Issue #5: Local Development Request Size Limit

Error: Request larger than 1MB fails in wrangler dev Source: https://developers.cloudflare.com/browser-rendering/faq/#does-local-development-support-all-browser-rendering-features Why It Happens: Local development limitation Prevention: Use remote: true in browser binding for local dev

Solution:

// wrangler.jsonc for local development
{
  "browser": {
    "binding": "MYBROWSER",
    "remote": true  // Use real headless browser during dev
  }
}

Issue #6: Bot Protection Always Triggered

Error: Website blocks requests as bot traffic Source: https://developers.cloudflare.com/browser-rendering/faq/#will-browser-rendering-bypass-cloudflares-bot-protection Why It Happens: Browser Rendering requests always identified as bots Prevention: Cannot bypass; if scraping your own zone, create WAF skip rule (requires Enterprise plan for Bot Management)

Solution:

// ❌ Cannot bypass bot protection
// Requests will always be identified as bots

// ✅ If scraping your own Cloudflare zone (Enterprise plan only):
// 1. Go to Security > WAF > Custom rules
// 2. Create skip rule with custom header:
//    Header: X-Custom-Auth
//    Value: your-secret-token
// 3. Pass header in your scraping requests

await page.setExtraHTTPHeaders({
  'X-Custom-Auth': 'your-secret-token'
});

// Note: Automatic headers are included:
// - cf-biso-request-id
// - cf-biso-devtools

Important: Free/Pro/Business plans CANNOT bypass bot detection even on their own sites. Enterprise plan with Bot Management is required for WAF allowlisting.

Issue #7: page.evaluate() Function Name Injection (__name Error)

Error: ReferenceError: __name is not defined Source: GitHub Issue #7107 Why It Happens: esbuild minification (wrangler 3.80.1+) injects __name() helper calls in arrow functions with nested function declarations. These run in browser context where the helper doesn't exist. Prevention: Keep page.evaluate() functions simple - avoid nested function declarations Applies to: wrangler 3.80.1 - 3.83.0 (fixed in 3.83.0+)

Solution:

// ❌ Avoid nested function declarations
const data = await page.evaluate(async () => {
  function toNumber(str: string | undefined): number | undefined {
    const num = typeof str === 'string' ? str.replaceAll('.', '').replaceAll(',', '.').match(/[+-]?([0-9]*[.])?[0-9]+/) : false;
    if (num) {
      return Number(num[0]);
    } else {
      return undefined;
    }
  }
  return toNumber('123.456');
});
// Error: ReferenceError: __name is not defined

// ✅ Inline the logic without nested functions
const data = await page.evaluate(async () => {
  const str = '123.456';
  const num = typeof str === 'string' ? str.replaceAll('.', '').replaceAll(',', '.').match(/[+-]?([0-9]*[.])?[0-9]+/) : false;
  return num ? Number(num[0]) : undefined;
});

// ✅ Or update to wrangler 3.83.0+
// npm install wrangler@latest

Note: This also affects page.waitForSelector() with complex callbacks. Fixed in wrangler 3.83.0+ (Nov 2024).

Issue #8: waitForSelector() Timeout Behavior Changed

Error: Code that relied on indefinite waiting now times out Source: Changelog 2026-01-07 Why It Happens: waitForSelector() previously did NOT timeout when selectors weren't found (hung indefinitely). This was fixed to properly honor timeout values. Prevention: Always set explicit timeouts and handle timeout errors Applies to: All code written before Jan 2026 that relied on indefinite waiting

Solution:

// ❌ Old behavior - would hang forever if selector not found
await page.waitForSelector('#dynamic-element');

// ✅ New behavior - properly times out (set explicit timeout)
try {
  await page.waitForSelector('#dynamic-element', { timeout: 5000 });
} catch (error) {
  if (error.name === 'TimeoutError') {
    console.log('Element not found within 5 seconds');
    // Handle missing element gracefully
  } else {
    throw error;
  }
}

// ✅ Use longer timeout for slow-loading elements
await page.waitForSelector('#slow-element', { timeout: 30000 }); // 30 seconds

Note: This is a breaking fix (behavior change). Code that relied on indefinite waiting will now timeout and throw errors. Always handle TimeoutError gracefully.

Production Checklist

Before deploying Browser Rendering Workers to production:

Configuration

Browser binding configured in wrangler.jsonc
nodejs_compat flag enabled (required for Browser Rendering)
Keep-alive timeout set if tasks take > 60 seconds
Remote binding enabled for local development if needed

Error Handling

Retry logic implemented for rate limits
Timeout handling for page.goto()
Browser cleanup in try-finally blocks
Concurrency limit checks before launching browsers
Graceful degradation when browser unavailable

Performance

Session reuse implemented for high-traffic routes
Multiple tabs used instead of multiple browsers
Incognito contexts for session isolation
KV caching for repeated screenshots/PDFs
Batch operations to maximize browser utilization

Monitoring

Log browser session IDs for debugging
Track browser duration for billing estimates
Monitor concurrency usage with puppeteer.limits()
Alert on rate limit errors
Dashboard monitoring at https://dash.cloudflare.com/?to=/:account/workers/browser-rendering

Security

Input validation for URLs (prevent SSRF)
Timeout limits to prevent abuse
Rate limiting on public endpoints
Authentication for sensitive scraping endpoints
WAF rules if scraping your own zone

Testing

Test screenshot capture with various page sizes
Test PDF generation with custom HTML
Test scraping with dynamic content (networkidle0)
Test error scenarios (invalid URLs, timeouts)
Load test concurrency limits

Error Handling Best Practices

Production Pattern - Use try-catch with proper cleanup:

async function withBrowser<T>(env: Env, fn: (browser: Browser) => Promise<T>): Promise<T> {
  let browser: Browser | null = null;

  try {
    // 1. Check limits before launching
    const limits = await puppeteer.limits(env.MYBROWSER);
    if (limits.allowedBrowserAcquisitions === 0) {
      throw new Error("Rate limit reached");
    }

    // 2. Try session reuse first
    const sessions = await puppeteer.sessions(env.MYBROWSER);
    const freeSessions = sessions.filter(s => !s.connectionId);
    browser = freeSessions.length > 0
      ? await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId)
      : await puppeteer.launch(env.MYBROWSER);

    // 3. Execute user function
    const result = await fn(browser);

    // 4. Disconnect (keep alive)
    await browser.disconnect();
    return result;
  } catch (error) {
    // 5. Close on error
    if (browser) await browser.close();
    throw error;
  }
}

Key Principles : Check limits → Reuse sessions → Execute → Disconnect on success, close on error

Using Bundled Resources

Templates (templates/)

Ready-to-use code templates for common patterns:

basic-screenshot.ts - Minimal screenshot example
screenshot-with-kv-cache.ts - Screenshot with KV caching
pdf-generation.ts - Generate PDFs from HTML or URLs
web-scraper-basic.ts - Basic web scraping pattern
web-scraper-batch.ts - Batch scrape multiple URLs
session-reuse.ts - Session reuse for performance
ai-enhanced-scraper.ts - Scraping with Workers AI
playwright-example.ts - Playwright alternative example
wrangler-browser-config.jsonc - Browser binding configuration

Usage:

# Copy template to your project
cp ~/.claude/skills/cloudflare-browser-rendering/templates/basic-screenshot.ts src/index.ts

References (references/)

Deep-dive documentation:

session-management.md - Complete session reuse guide
pricing-and-limits.md - Detailed pricing breakdown
common-errors.md - All known issues and solutions
puppeteer-vs-playwright.md - Feature comparison and migration

When to load: Reference when implementing advanced patterns or debugging specific issues.

Dependencies

Required:

@cloudflare/puppeteer@1.0.4 - Puppeteer for Workers
wrangler@4.43.0+ - Cloudflare CLI

Optional:

@cloudflare/playwright@1.0.0 - Playwright for Workers (alternative)
@cloudflare/workers-types@4.20251014.0+ - TypeScript types

Related Skills:

cloudflare-worker-base - Worker setup with Hono
cloudflare-kv - KV caching for screenshots
cloudflare-r2 - R2 storage for generated files
cloudflare-workers-ai - AI-enhanced scraping

Official Documentation

Browser Rendering Docs : https://developers.cloudflare.com/browser-rendering/
Puppeteer API : https://pptr.dev/api/
Playwright API : https://playwright.dev/docs/api/class-playwright
Cloudflare Puppeteer Fork : https://github.com/cloudflare/puppeteer
Cloudflare Playwright Fork : https://github.com/cloudflare/playwright
Pricing : https://developers.cloudflare.com/browser-rendering/platform/pricing/
Limits : https://developers.cloudflare.com/browser-rendering/platform/limits/

Package Versions (Verified 2026-01-21)

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

Alternative (Playwright):

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

Note: Playwright v1.1.0 includes support for Playwright v1.57 (Jan 2026). Wrangler 3.83.0+ fixes the page.evaluate() __name injection bug.

Troubleshooting

Problem: "Cannot read properties of undefined (reading 'fetch')"

Solution: Pass browser binding to puppeteer.launch():

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

Problem: XPath selectors not working

Solution: Use CSS selectors or page.evaluate() with XPathEvaluator (see Issue #1)

Problem: Browser closes after 60 seconds

Solution: Extend timeout with keep_alive:

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

Problem: Rate limit reached

Solution: Reuse sessions, use tabs, check limits before launching (see Issue #4)

Problem: Local dev request > 1MB fails

Solution: Enable remote binding in wrangler.jsonc:

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

Problem: Website blocks as bot

Solution: Cannot bypass. If your own zone, create WAF skip rule (see Issue #6)

Questions? Issues?

Check references/common-errors.md for detailed solutions
Review references/session-management.md for performance optimization
Verify browser binding is configured in wrangler.jsonc
Check official docs: https://developers.cloudflare.com/browser-rendering/
Ensure nodejs_compat compatibility flag is enabled

Weekly Installs

341

Repository

jezweb/claude-skills

GitHub Stars

643

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn

Installed on

claude-code271

gemini-cli226

opencode223

cursor209

antigravity203

codex196

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

68,100 周安装

page.click(selector)

Cloudflare Browser Rendering 浏览器自动化指南：Puppeteer与Playwright API完整参考

🇨🇳中文介绍

Cloudflare Browser Rendering - 完整参考

目录

快速开始 (5分钟)

1. 添加浏览器绑定

相关 Skills

2. 安装 Puppeteer

3. 拍摄第一张截图

4. 部署

Browser Rendering 概述

什么是 Browser Rendering？

两种集成方法

Puppeteer 与 Playwright 对比

Puppeteer API 参考

Playwright API 参考

会话管理

会话复用模式 (关键)

浏览器上下文 (Cookie/缓存隔离)

多标签页模式

常用模式

带 KV 缓存的截图

AI 增强的抓取

定价与限制

已知问题预防

问题 #1: 不支持 XPath 选择器

问题 #2: 未传递浏览器绑定 (Fetcher 类型混淆)

问题 #3: 浏览器超时 (60 秒)

问题 #4: 达到并发限制

问题 #5: 本地开发请求大小限制

问题 #6: 始终触发机器人防护

问题 #7: page.evaluate() 函数名注入 (__name 错误)

问题 #8: waitForSelector() 超时行为已更改

生产环境检查清单

配置

错误处理

性能

监控

安全

测试

错误处理最佳实践

使用捆绑资源

模板 (templates/)

参考 (references/)

依赖项

官方文档

包版本 (已验证 2026-01-21)

故障排除

问题: "Cannot read properties of undefined (reading 'fetch')"

问题: XPath 选择器不工作

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

问题: 达到速率限制

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

问题: 网站阻止为机器人

🇺🇸English

Cloudflare Browser Rendering - Complete Reference

Table of Contents

Quick Start (5 minutes)

1. Add Browser Binding

2. Install Puppeteer

3. Take Your First Screenshot

4. Deploy

Browser Rendering Overview

What is Browser Rendering?

Two Integration Methods

Puppeteer vs Playwright

Puppeteer API Reference

Playwright API Reference

Session Management

Session Reuse Pattern (Critical)

Browser Contexts (Cookie/Cache Isolation)

Multiple Tabs Pattern

Common Patterns

Screenshot with KV Caching

AI-Enhanced Scraping

Pricing & Limits

Known Issues Prevention

Issue #1: XPath Selectors Not Supported

Issue #2: Browser Binding Not Passed (Fetcher Type Confusion)

Issue #3: Browser Timeout (60 seconds)