Cloudflare Browser Rendering 提供运行在 Cloudflare 全球网络上的无头 Chromium 浏览器，让你可以使用熟悉的 Puppeteer 和 Playwright 工具来自动化浏览器任务。该技能文档是一个生产就绪的知识域，用于构建基于 Cloudflare Browser Rendering 的浏览器自动化工作流。
用途
Browser Rendering 主要用于以下场景：
- 截图：捕获网页的视觉快照
- PDF 生成：将 HTML 或 URL 转换为 PDF
- 网页抓取：从动态网站提取内容
- 测试：自动化前端测试
- 爬取：导航多页面工作流
主要能力
该服务提供两种集成方式：Workers 绑定（适合复杂自动化、自定义工作流、会话管理，属于高级方式）和 REST API（适合简单的截图/PDF 任务）。本技能覆盖 Workers 绑定方式，提供完整的 Puppeteer/Playwright API。
Puppeteer 与 Playwright 对比：
- Puppeteer 使用 @cloudflare/puppeteer@1.0.4，API 最流行，具备高级会话管理 API，仅支持 Chromium，适合截图、PDF、抓取。
- Playwright 使用 @cloudflare/playwright@1.0.0，采用度增长中，会话管理为基础级别，仅支持 Chromium（暂不支持 Firefox/Safari），适合测试和前端自动化。
推荐：大多数用例使用 Puppeteer；如果已有 Playwright 测试或需要 MCP 集成，则使用 Playwright。
使用方式
快速开始（5 分钟）：
- 添加 Browser 绑定。在 wrangler.jsonc 中配置 browser 绑定，并启用 nodejs_compat 兼容标志（Browser Rendering 需要 Node.js API 和 polyfill）。
- 安装 Puppeteer：npm install @cloudflare/puppeteer
- 编写 Worker 代码：使用 puppeteer.launch(env.MYBROWSER) 启动浏览器，创建页面，导航并截图，最后关闭浏览器。
- 部署：npx wrangler deploy
关键规则：
- 必须将 env.MYBROWSER 传给 puppeteer.launch()（不能为 undefined）
- 完成后必须调用 browser.close()，或使用 browser.disconnect() 以复用会话
- 必须使用 nodejs_compat 兼容标志
会话管理：启动新浏览器速度慢且消耗并发限制，复用会话可加快响应、降低并发占用。使用 puppeteer.sessions() 列出运行中的会话，筛选无 connectionId 的空闲会话，通过 puppeteer.connect() 连接。成功时使用 browser.disconnect() 保持会话存活，仅在出错或真正完成时使用 browser.close()。
浏览器上下文：使用 browser.createBrowserContext() 共享浏览器但隔离 cookie 和缓存。
多标签页模式：不要为 10 个 URL 启动 10 个浏览器，而应使用 1 个浏览器加 10 个标签页（通过 Promise.all() 和 browser.newPage()）。
常见模式：
- 带 KV 缓存的截图：先检查 KV 缓存，未命中时启动浏览器截图并缓存 24 小时。
- AI 增强抓取：结合 Workers AI 从页面 HTML 中提取结构化数据。
- 其他模式：PDF 生成（page.pdf()）、结构化抓取（page.evaluate()）、表单自动化（page.type() + page.click()）。
适用场景
适合需要在 Cloudflare Workers 中运行无头浏览器自动化的开发者，包括截图服务、PDF 生成服务、动态网页抓取、前端自动化测试、多页面爬取等。
限制
定价与限制（计费于 2025 年 8 月 20 日正式可用）：
- 免费层：每天 10 分钟，3 个并发，每分钟 3 次启动，60 秒超时。
- 付费层：每月包含 10 小时（超出后 $0.09/小时），30 个并发（超出后 $2.00/浏览器），每分钟 30 次启动，超时 60 秒至 10 分钟。
- 并发计算：每日峰值使用量的月平均值。
- 速率限制：按固定每秒填充率执行，不支持突发。30 请求/分钟即每 2 秒 1 个请求，即使配额未用完也不能一次性发送全部 30 个请求。启动前应检查 puppeteer.limits(env.MYBROWSER)。
已知问题预防（该技能预防 8 个已记录问题）：
- 不支持 XPath 选择器（对 Workers 有安全风险），应使用 CSS 选择器或 page.evaluate() 配合 XPathEvaluator。
- 未传递浏览器绑定（Fetcher 类型混淆），必须将 env.MYBROWSER 传给 puppeteer.launch() 或 chromium.launch() 包装器，不能直接调用 env.MYBROWSER.launch()。
- 浏览器超时（默认 60 秒无活动），可使用 keep_alive 选项延长至最多 10 分钟。
- 达到并发限制，应复用会话、使用标签页而非多浏览器、启动前检查限制、按每秒速率节流请求。
- 本地开发请求大小限制（文档内容在此处截断，后续细节暂未提供）。
其他限制：仅支持 Chromium 浏览器；Playwright 暂不支持 Firefox/Safari；XPath 选择器不可用。
最新版本：@cloudflare/puppeteer@1.0.4、@cloudflare/playwright@1.1.0、wrangler@4.59.3。文档最后更新于 2026-01-21。