Cloudflare Browser Rendering 实战模式在 Workers 中驾驭无头浏览器的 9 种核心模式【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文以 Cloudflare Browser Rendering 的模式文档为主线系统讲解如何在 Cloudflare Workers 中使用cloudflare/puppeteer与cloudflare/playwright绑定完成截图、PDF 生成、数据抓取、表单自动化与并发爬取等典型任务并补充会话复用、配额检查、错误处理等生产级最佳实践。读完本文你将掌握 Browser Rendering Workers 绑定从最小可用到可上生产的完整代码范式并能直接在 Wrangler 工程中落地。背景与前置条件Cloudflare Browser Rendering 允许你在 Cloudflare 全球网络上调度无头 Chromium通过 Workers 绑定 在 Worker 内直接驱动浏览器常见场景包括网页截图、生成 PDF、Web 抓取、浏览器自动化、Web 应用测试、结构化数据提取与页面指标采集。在进入模式代码之前需要先完成三件事安装 Cloudflare 专用包必须使用cloudflare/puppeteer或cloudflare/playwright标准puppeteer/playwright无法在 Workers 运行时工作npm install cloudflare/puppeteer # 或 cloudflare/playwright配置wrangler.json声明browser绑定并开启nodejs_compat兼容性标志完整配置说明见 configuration.md{ name: browser-worker, main: src/index.ts, compatibility_date: 2025-01-01, compatibility_flags: [nodejs_compat], browser: { binding: MYBROWSER } }本地开发必须使用--remote模式本地模式不支持 Browser Rendering 绑定wrangler dev --remote是必须的否则会报MYBROWSER is undefined。环境类型声明可以这样写interface Env { MYBROWSER: Fetcher; }绑定类型为Fetcher参见 bindings/api.md 中的类型对照表。在 SKILL.md 的媒体类决策树中Browser Rendering 被归类为浏览器自动化/截图场景的推荐产品当需求是一次性、无状态任务时官方建议走 REST API而复杂的浏览器自动化工作流、多页面交互、会话复用与生产级应用则应优先使用 Workers 绑定详见 README.md 的决策树。本文所有模式均面向 Workers 绑定。模式一Basic Worker —— 最小可用的渲染入口最基础的模式是启动浏览器 → 打开页面 → 返回渲染后的 HTML关键要点是关闭浏览器的操作必须放在finally中确保无论成功失败都不会泄漏会话import puppeteer from cloudflare/puppeteer; export default { async fetch(request, env) { const browser await puppeteer.launch(env.MYBROWSER); try { const page await browser.newPage(); await page.goto(https://example.com); return new Response(await page.content()); } finally { await browser.close(); // ALWAYS in finally } } };为什么必须 finally 关闭在 Workers 绑定下浏览器会话由你全权管理REST API 会在超时后自动关闭但 Workers 必须显式调用close()否则会话会一直存活到keep_alive过期白白占用并发配额详见 gotchas.md。这也是下面所有模式的一致纪律。模式二Session Reuse —— 会话复用把冷启动变成热连接每次launch都是一次冷启动约 12 秒而连接已有会话warm connect只需约 100200 毫秒。对性能敏感的生产应用应当把sessionId持久化到 KV让后续请求直接connect复用let sessionId await env.SESSION_KV.get(browser-session); if (sessionId) { browser await puppeteer.connect(env.MYBROWSER, sessionId); } else { browser await puppeteer.launch(env.MYBROWSER, { keep_alive: 600000 }); await env.SESSION_KV.put(browser-session, browser.sessionId(), { expirationTtl: 600 }); } // Dont close browser to keep session alive要点说明keep_alive最大 600000ms10 分钟且与套餐无关——免费版与付费版的会话保活上限相同KV 写入的expirationTtl: 600秒与浏览器的 10 分钟保活窗口对齐保证 KV 中的 sessionId 不会指向已过期的会话会话复用模式故意不调用close()以维持会话存活这与模式一的纪律形成对照——选择哪种取决于你的请求是一次性渲染还是频繁短请求KV 命名空间的创建与绑定方式见 kv/configuration.mdKV 会话管理更完整的读写范式可参考 kv/patterns.md 中的 Session Management 一节。模式三Common Operations —— 高频操作速查文档以表格形式给出五种最常见的页面操作这里逐条展开并补充参数细节任务代码说明截图await page.screenshot({ type: png, fullPage: true })type支持png/jpegfullPage截取整页而非可视区还支持clip裁剪PDFawait page.pdf({ format: A4, printBackground: true })format支持A4/Letter/Legal可配landscape、margin提取数据await page.evaluate(() document.querySelector(h1).textContent)在页面上下文执行 JS注意闭包问题见下方提取数据的三条铁律填充表单await page.type(#input, value); await page.click(button)先输入后点击可配合waitForNavigation等待提交跳转等待导航await Promise.all([page.waitForNavigation(), page.click(a)])并行监听导航事件与触发点击避免竞态提取数据的三条铁律来自 gotchas.md外部作用域变量不可用page.evaluate在页面上下文执行闭包捕获的 Worker 作用域变量无法访问必须显式传参await page.evaluate((sel) document.querySelector(sel)?.textContent, selector)DOM 可能缺失页面元素不存在时querySelector返回null务必使用?.可选链否则会抛Evaluation failed。模式四Parallel Scraping —— 单浏览器多页并发抓取并行抓取的核心思想是用一个浏览器 多页面代替多个浏览器。因为免费版并发会话上限只有 3 个一次launch三个浏览器就会直接触顶而单浏览器内的多页面完全不受会话数限制const pages await Promise.all(urls.map(() browser.newPage())); await Promise.all(pages.map((p, i) p.goto(urls[i]))); const titles await Promise.all(pages.map(p p.title()));三个Promise.all依次负责建页 → 导航 → 取数三个阶段都完全并行。注意每个 page 对象在数组中的索引与 URL 一一对应方便后续按 URL 归并结果。这种1 会话 N 页面的写法同样是 gotchas.md 中Optimize Concurrency一节推荐的正确姿势。模式五Playwright Selectors —— 现代语义化选择器如果选择 Playwright 路线cloudflare/playwright可以用更高层的语义化选择器替代 CSS 选择器代码可读性和抗页面结构变化的能力都更强import { launch } from cloudflare/playwright; const browser await launch(env.MYBROWSER); await page.getByRole(button, { name: Sign in }).click(); await page.getByLabel(Email).fill(userexample.com); await page.getByTestId(submit-button).click();Puppeteer vs Playwright 怎么选来自 README.md维度PuppeteerPlaywrightAPI 风格Chrome DevTools Protocol高层抽象选择器CSS、XPathCSS、文本、role、test-id擅长高级控制、CDP 访问快速自动化、测试学习曲线较陡平缓需要 CDP 协议访问、Chrome 专有特性或迁移既有 Puppeteer 代码 → 选 Puppeteer追求现代选择器 API、跨浏览器模式和更快开发速度 → 选 Playwright。Playwright 还支持通过browser.newContext()自定义viewport与userAgent完整示例见 api.md。模式六Incognito Contexts —— 无痕上下文隔离无痕浏览器上下文可以在不创建多个浏览器会话的前提下实现隔离——每个上下文拥有独立的 cookies 与存储非常适合多用户模拟、多账号测试等场景const ctx1 await browser.createIncognitoBrowserContext(); const ctx2 await browser.createIncognitoBrowserContext(); // Each has isolated cookies/storage在 Playwright 中对应的概念是browser.newContext()可传入 viewport、userAgent 等选项。相比每用户一个浏览器的粗暴做法无痕上下文只占用同一会话内的资源既满足隔离需求又守住并发配额。模式七Quota Check —— 配额检查与优雅降级Browser Rendering 有明确的套餐额度gotchas.md 中有完整表格免费版每日浏览器时间 10 分钟、并发会话 3 个、每分钟请求 6 次付费版并发 30、每分钟 180每日时间不受限受公平使用政策约束。因此在任务开始前先检查剩余配额可以避免任务中途失败const limits await puppeteer.limits(env.MYBROWSER); if (limits.remaining 60000) return new Response(Quota low, { status: 429 });limits返回值形如{ remaining: 540000, total: 600000, concurrent: 2 }单位毫秒其中remaining表示剩余浏览器时间、concurrent表示当前并发会话数。此外还可以用await puppeteer.sessions(env.MYBROWSER)列出当前全部会话排查是否存在泄漏的会话。模式八Error Handling —— 分类处理与兜底关闭生产级 Worker 必须对不同错误给出不同响应超时 → 504、会话超限 → 429并且无论何种错误都要确保浏览器被关闭try { await page.goto(url, { timeout: 30000, waitUntil: networkidle0 }); } catch (e) { if (e.message.includes(timeout)) return new Response(Timeout, { status: 504 }); if (e.message.includes(Session limit)) return new Response(Too many sessions, { status: 429 }); } finally { if (browser) await browser.close(); }再对照 gotchas.md 中的常见错误速查表错误成因对策Session limit exceeded并发会话过多关闭闲置浏览器用多页面替代多浏览器Page navigation timeout页面慢或繁忙页上的networkidle等待增大 timeout改用waitUntil: loadSession not found会话已过期捕获错误后重新 launch 新会话Evaluation failedDOM 元素缺失使用?.可选链Protocol error: Target closed操作期间页面已关闭关闭前 await 全部操作模式九性能调优 —— waitUntil 与资源拦截两个来自 gotchas.md 的调优手段能显著缩短单次任务耗时、节省配额时间1. 按需选择waitUntil从快到慢domcontentloaded—— DOM 就绪即返回最快load—— load 事件默认值networkidle0—— 网络空闲 500ms最慢但最稳。2. 拦截并阻断不必要的资源await page.setRequestInterception(true); page.on(request, (req) { if ([image, stylesheet, font].includes(req.resourceType())) { req.abort(); } else { req.continue(); } });对纯数据抓取场景阻断图片、样式与字体可大幅减少带宽与等待时间配合会话复用冷启动 ~1-2s、热连接 ~100-200ms可将抓取服务的整体延迟控制在一个很低的水平。组合实战一个完整的抓取 Worker把上述模式组合起来可以得到一个生产可用的参考实现KV 存会话 配额预检 无痕上下文 分类错误处理import puppeteer from cloudflare/puppeteer; interface Env { MYBROWSER: Fetcher; SESSION_KV: KVNamespace; } export default { async fetch(request: Request, env: Env): PromiseResponse { const limits await puppeteer.limits(env.MYBROWSER); if (limits.remaining 60000) return new Response(Quota low, { status: 429 }); let browser; try { const sessionId await env.SESSION_KV.get(browser-session); if (sessionId) { browser await puppeteer.connect(env.MYBROWSER, sessionId); } else { browser await puppeteer.launch(env.MYBROWSER, { keep_alive: 600000 }); await env.SESSION_KV.put(browser-session, browser.sessionId(), { expirationTtl: 600 }); } const ctx await browser.createIncognitoBrowserContext(); const page await ctx.newPage(); await page.goto(https://example.com, { waitUntil: domcontentloaded }); const title await page.evaluate(() document.title); return new Response(h1${title}/h1); } catch (e: any) { if (e.message.includes(timeout)) return new Response(Timeout, { status: 504 }); if (e.message.includes(Session limit)) return new Response(Too many sessions, { status: 429 }); return new Response(Error, { status: 500 }); } finally { // 会话复用模式下不关闭浏览器让保活窗口内的后续请求复用 } } } satisfies ExportedHandlerEnv;注意该示例采用会话复用策略因此finally中不调用close()如果你的 Worker 是低频一次性任务应改回始终 finally 关闭的模式一写法避免长期占用会话配额。小结本文完整继承了 patterns.md 的九大核心模式并补充了来自 configuration.md、api.md、gotchas.md 与 README.md 的配置、配额、选型与排障细节。实践中的三条铁律请牢记该关闭就关闭一次性任务永远在finally中close()避免会话泄漏该复用就复用高频请求用 KV 持久化 sessionId把冷启动换成 100200ms 的热连接先查配额再动手用puppeteer.limits预检用多页面而非多浏览器应对并发把免费版 3 个并发会话花在刀刃上。如需进一步深入 REST API 端点/screenshot、/pdf、/scrape、/json等或套餐上限细节可继续查阅 api.md 与 gotchas.md。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
