cloudflare-browser-rendering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Browser Rendering - Complete Reference

Cloudflare Browser Rendering 完整参考文档

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

Status: Production Ready ✅ Last Updated: 2025-11-25 Dependencies: cloudflare-worker-base (for Worker setup) Latest Versions: @cloudflare/puppeteer@1.0.4, @cloudflare/playwright@1.0.0, wrangler@4.50.0, @cloudflare/workers-types@4.20251125.0

用于构建基于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

Quick Start (5 minutes)

快速入门（5分钟）

1. Add Browser Binding

1. 添加浏览器绑定

wrangler.jsonc:

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.

wrangler.jsonc:

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. Install Puppeteer

2. 安装Puppeteer

bash

bun add @cloudflare/puppeteer

bash

bun add @cloudflare/puppeteer

3. Take Your First Screenshot

3. 拍摄第一张截图

typescript

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

typescript

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

4. 部署

bash

bunx 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

bash

bunx wrangler deploy

测试地址：

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

重要提示:

务必将
```
env.MYBROWSER
```
传入
```
puppeteer.launch()
```
（不能传undefined）
使用完成后务必调用
```
browser.close()
```
（或使用
```
browser.disconnect()
```
复用会话）
启用
```
nodejs_compat
```
兼容性标志

When to Load References

何时加载参考文档

Load immediately when user mentions:

```
puppeteer-api.md
```
→ "API reference", "Puppeteer methods", "Browser class", "Page methods", "complete API"
```
patterns.md
```
→ "examples", "how to", "screenshot", "PDF", "scraping", "automation", "form filling"
```
session-management.md
```
→ "sessions", "hibernation", "connection pooling", "state management", "Durable Objects"
```
pricing-and-limits.md
```
→ "cost", "pricing", "limits", "quotas", "billing", "rate limits"
```
common-errors.md
```
→ errors, debugging, "not working", troubleshooting, "issue #4", "issue #5", "issue #6"
```
puppeteer-vs-playwright.md
```
→ "Playwright", "comparison", "which library", "differences"

Load proactively when:

Building new automation → Load
```
patterns.md
```
Debugging errors → Load
```
common-errors.md
```
Optimizing costs → Load
```
pricing-and-limits.md
```
Managing sessions → Load
```
session-management.md
```
Need complete API → Load
```
puppeteer-api.md
```

当用户提及以下内容时立即加载:

```
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 Overview

Browser Rendering概述

What is Browser Rendering?

什么是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

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

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

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

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

本技能覆盖Workers绑定方式（具备完整Puppeteer/Playwright API的高级方法）。

Puppeteer vs Playwright

Puppeteer与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	Playwright
API熟悉度	最受欢迎	采用率持续增长
包	`@cloudflare/puppeteer@1.0.4`	`@cloudflare/playwright@1.0.0`
会话管理	✅ 高级API	⚠️ 基础功能
浏览器支持	仅Chromium	仅Chromium（暂不支持Firefox/Safari）
适用场景	截图、PDF、抓取	测试、前端自动化

建议：大多数场景使用Puppeteer。如果你已在使用Playwright进行测试，那么它是理想选择。

Puppeteer API Reference

Puppeteer API参考

Core classes for browser automation:

Core Functions -

launch()

connect()

sessions()

history()

limits()

Browser API -

newPage()

sessionId()

close()

disconnect()

createBrowserContext()

Page API -

goto()

screenshot()

pdf()

content()

setContent()

evaluate()

waitForSelector()

type()

click()

Quick Example:

typescript

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

Load
references/puppeteer-api.md
when implementing browser automation, scraping, debugging Puppeteer-specific issues, or needing complete API signatures and method details.

浏览器自动化核心类:

核心函数 -

launch()

、

connect()

、

sessions()

、

history()

、

limits()

Browser API -

newPage()

、

sessionId()

、

close()

、

disconnect()

、

createBrowserContext()

Page API -

goto()

、

screenshot()

、

pdf()

、

content()

、

setContent()

、

evaluate()

、

waitForSelector()

、

type()

、

click()

快速示例:

typescript

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 Reference

Playwright API参考

Playwright provides a similar API to Puppeteer with slight differences.

Playwright提供与Puppeteer类似的API，但存在细微差异。

Installation

安装

bash

bun add @cloudflare/playwright

bash

bun add @cloudflare/playwright

Basic Example

基础示例

typescript

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

typescript

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

Key Differences from Puppeteer

与Puppeteer的主要差异

Feature	Puppeteer	Playwright
Import	`import puppeteer from "@cloudflare/puppeteer"`	`import { chromium } from "@cloudflare/playwright"`
Launch	`puppeteer.launch(env.MYBROWSER)`	`chromium.launch(env.BROWSER)`
Session API	✅ Advanced (sessions, history, limits)	⚠️ Basic
Auto-waiting	Manual `waitForSelector()`	Built-in auto-waiting
Selectors	CSS only	CSS, text, XPath (via evaluate workaround)

Recommendation: Stick with Puppeteer unless you have existing Playwright tests to migrate.

特性	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。

Session Management

会话管理

Browser sessions are managed using Durable Objects for state persistence across multiple requests. Sessions support hibernation, automatic cleanup, and concurrent connection handling.

Key Patterns:

Session Reuse - Use
```
puppeteer.sessions()
```
and
```
puppeteer.connect()
```
to reuse browsers
Browser Contexts - Isolate cookies/cache while sharing browser instance
Multiple Tabs - Use tabs (
```
newPage()
```
) instead of multiple browsers for batch operations
Disconnect vs Close - Use
```
disconnect()
```
to keep session alive,
```
close()
```
to terminate

Load
references/session-management.md
for complete session lifecycle management, hibernation patterns, connection pooling strategies, and production examples.

浏览器会话使用Durable Objects进行跨多个请求的状态持久化。会话支持休眠、自动清理和并发连接处理。

核心模式:

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

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

Common Patterns

常见模式

6 production-ready browser automation patterns:

Screenshot with KV Caching - Cache screenshots for high-traffic URLs, reduce browser usage
PDF Generation from HTML - Convert custom HTML to PDF for invoices, reports, documents
Web Scraping with Structured Data - Extract product information, prices, content from web pages
Batch Scraping Multiple URLs - Efficiently scrape multiple sites using tabs in single browser
AI-Enhanced Scraping - Combine Browser Rendering with Workers AI for adaptive data extraction
Form Filling and Automation - Automate login flows, form submissions, multi-step workflows

Quick Example (Screenshot with caching):

typescript

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

Load
references/patterns.md
when implementing browser automation patterns, scraping, PDF generation, or needing complete production examples with error handling and optimizations.

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

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

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

typescript

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
。

Pricing & Limits

定价与限制

Browser Rendering charges based on CPU time (paid plans only). Free tier: 10 minutes/day. Paid tier: 10 hours/month included, then $0.09 per browser hour + $2.00 per concurrent browser above 10.

Load
references/pricing-and-limits.md
for complete pricing tiers, quota details, rate limiting strategies, and cost optimization techniques.

Browser Rendering基于CPU时间收费（仅付费计划可用）。免费额度：每天10分钟。付费额度：每月包含10小时，超出后每浏览器小时0.09美元 + 超过10个并发浏览器后每个并发浏览器2.00美元。

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

Known Issues Prevention

已知问题预防

This skill prevents 6 documented issues. Top 3 critical errors detailed below:

本技能可预防6个已记录的问题。以下是前3个关键错误的详细说明：

Issue #1: XPath Selectors Not Supported ⚠️

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

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:

typescript

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

错误信息："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

解决方案:

typescript

// ❌ 不要直接使用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;
});

Issue #2: Browser Binding Not Passed ⚠️

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

Error: "Cannot read properties of undefined (reading 'fetch')" Source: https://developers.cloudflare.com/browser-rendering/faq/#cannot-read-properties-of-undefined-reading-fetch Why It Happens:

puppeteer.launch()

called without browser binding Prevention: Always pass

env.MYBROWSER

to launch

Solution:

typescript

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

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

错误信息："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方法

解决方案:

typescript

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

// ✅ 传入绑定
const browser = await puppeteer.launch(env.MYBROWSER);

Issue #3: Browser Timeout (60 seconds) ⚠️

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

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:

typescript

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

错误信息：浏览器在60秒后意外关闭来源：https://developers.cloudflare.com/browser-rendering/platform/limits/#note-on-browser-timeout 问题原因：默认无活动超时为60秒 预防方案：使用

keep_alive

选项将超时延长至最多10分钟

解决方案:

typescript

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

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

Additional Issues (4-6)

其他问题（4-6）

Load
references/common-errors.md
for complete error catalog including:

Issue #4: Concurrency limits and rate limiting
Issue #5: Local development request size limits
Issue #6: Bot protection and WAF bypass strategies

Plus solutions for page crashes, authentication issues, resource loading errors, and debugging strategies.

如需完整的错误目录，请加载
references/common-errors.md
，其中包括:

问题4：并发限制与限流
问题5：本地开发请求大小限制
问题6：机器人防护与WAF绕过策略

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

Production Checklist

生产环境检查清单

Critical Items Before Deployment:

✅ Browser binding +
```
nodejs_compat
```
flag configured
✅ Error handling with try-finally cleanup
✅ Rate limit checks and retry logic
✅ Session reuse for performance
✅ KV caching for repeated operations
✅ Input validation (prevent SSRF)
✅ Monitoring dashboard at https://dash.cloudflare.com

Load
references/patterns.md
for production-ready templates with complete error handling, monitoring, and security patterns.

部署前的关键事项:

✅ 已配置浏览器绑定 +
```
nodejs_compat
```
标志
✅ 已添加try-finally清理逻辑的错误处理
✅ 已实现限流检查与重试逻辑
✅ 已启用会话复用以提升性能
✅ 已为重复操作配置KV缓存
✅ 已添加输入验证（防止SSRF）
✅ 已配置监控仪表盘：https://dash.cloudflare.com

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

Dependencies

依赖项

Required:

@cloudflare/puppeteer@1.0.4

wrangler@4.50.0

@cloudflare/workers-types@4.20251125.0

Related Skills:

cloudflare-worker-base

(Worker setup),

cloudflare-kv

(caching),

cloudflare-workers-ai

(AI scraping)

必填：

@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抓取）

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/

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/

Package Versions (Verified 2025-11-27)

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

json

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

Alternative (Playwright):

json

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

json

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

替代方案（Playwright）:

json

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

Troubleshooting

故障排除

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

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

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

typescript

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

解决方案：将浏览器绑定传入puppeteer.launch():

typescript

const browser = await puppeteer.launch(env.MYBROWSER); // 不要只调用puppeteer.launch()

Problem: XPath selectors not working

问题：XPath选择器无法工作

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

解决方案：使用CSS选择器或在page.evaluate()中使用XPathEvaluator（参见问题1）

Problem: Browser closes after 60 seconds

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

Solution: Extend timeout with keep_alive:

typescript

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

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

typescript

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)

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

Problem: Local dev request > 1MB fails

问题：本地开发请求超过1MB失败

Solution: Enable remote binding in wrangler.jsonc:

jsonc

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

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

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

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

有疑问？遇到问题？

查看
```
references/common-errors.md
```
获取详细解决方案
查看
```
references/session-management.md
```
获取性能优化方案
验证wrangler.jsonc中是否已配置浏览器绑定
查看官方文档：https://developers.cloudflare.com/browser-rendering/
确保已启用
```
nodejs_compat
```
兼容性标志

cloudflare-browser-rendering

Original

Translation

Cloudflare Browser Rendering - Complete Reference

Cloudflare Browser Rendering 完整参考文档

Table of Contents

目录

Quick Start (5 minutes)

快速入门（5分钟）

1. Add Browser Binding

1. 添加浏览器绑定

2. Install Puppeteer

2. 安装Puppeteer

3. Take Your First Screenshot

3. 拍摄第一张截图

4. Deploy

4. 部署

When to Load References

何时加载参考文档

Browser Rendering Overview

Browser Rendering概述

What is Browser Rendering?

什么是Browser Rendering？

Two Integration Methods

两种集成方式

Puppeteer vs Playwright

Puppeteer与Playwright对比

Puppeteer API Reference

Puppeteer API参考

Playwright API Reference

Playwright API参考

Installation

安装

Basic Example

基础示例

Key Differences from Puppeteer

与Puppeteer的主要差异

Session Management

会话管理

Common Patterns

常见模式

Pricing & Limits

定价与限制

Known Issues Prevention

已知问题预防

Issue #1: XPath Selectors Not Supported ⚠️

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

Issue #2: Browser Binding Not Passed ⚠️

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

Issue #3: Browser Timeout (60 seconds) ⚠️

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

Additional Issues (4-6)

其他问题（4-6）

Production Checklist

生产环境检查清单

Dependencies

依赖项

Official Documentation

官方文档

Package Versions (Verified 2025-11-27)

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

Troubleshooting

故障排除

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

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

Problem: XPath selectors not working

问题：XPath选择器无法工作

Problem: Browser closes after 60 seconds

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

Problem: Rate limit reached

问题：达到限流阈值

Problem: Local dev request > 1MB fails

问题：本地开发请求超过1MB失败

Problem: Website blocks as bot

问题：网站将其识别为机器人并阻止