cloudflare-browser-rendering

Cloudflare Browser Rendering - 完全リファレンス

Cloudflare Browser Rendering を使用して、ブラウザー自動化ワークフローを構築するための、本番環境対応のナレッジドメインです。

ステータス：本番環境対応 ✅ 最終更新日：2025-11-25 依存関係：cloudflare-worker-base（Worker のセットアップ用） 最新バージョン：@cloudflare/[email protected]、@cloudflare/[email protected]、[email protected]、@cloudflare/[email protected]

---

目次

1. クイックスタート（5 分）
2. Browser Rendering の概要
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 とポリフィルが必要です。

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

    // 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. デプロイする

bunx wrangler deploy

テスト先：https://your-worker.workers.dev/?url=https://example.com

重要：

• puppeteer.launch() には必ず env.MYBROWSER を渡してください（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 → エラー、デバッグ、「動作しない」、「トラブルシューティング」、「issue #4」、「issue #5」、「issue #6」
• puppeteer-vs-playwright.md → 「Playwright」、「比較」、「どちらのライブラリ」、「違い」

次の場合は先回りして読み込みます：

• 新しい自動化を構築する → patterns.md を読み込む
• エラーをデバッグする → common-errors.md を読み込む
• コストを最適化する → pricing-and-limits.md を読み込む
• セッションを管理する → session-management.md を読み込む
• 完全な API が必要 → puppeteer-api.md を読み込む

---

Browser Rendering の概要

Browser Rendering とは？

Cloudflare Browser Rendering は、Cloudflare のグローバルネットワーク上で動作するヘッドレス Chromium ブラウザーを提供します。Puppeteer や Playwright などの使い慣れたツールを使って、ブラウザータスクを自動化できます。

• スクリーンショット - Web ページの画面イメージを取得します
• PDF 生成 - HTML／URL を PDF に変換します
• Web スクレイピング - 動的な Web サイトからコンテンツを抽出します
• テスト - フロントエンドテストを自動化します
• クローリング - 複数ページにわたるワークフローを巡回します

2 つの統合方法

方法	最適な用途	複雑さ
Workers バインディング	複雑な自動化、カスタムワークフロー、セッション管理	高度
REST API	シンプルなスクリーンショット／PDF タスク	シンプル

このスキルでは Workers バインディングを扱います（Puppeteer／Playwright の API をすべて利用できる高度な方法です）。

Puppeteer と Playwright の比較

機能	Puppeteer	Playwright
API の知名度	最も広く使われています	採用が拡大しています
パッケージ	@cloudflare/[email protected]	@cloudflare/[email protected]
セッション管理	✅ 高度な API	⚠️ 基本機能
ブラウザーのサポート	Chromium のみ	Chromium のみ（Firefox／Safari はまだサポートされていません）
最適な用途	スクリーンショット、PDF、スクレイピング	テスト、フロントエンド自動化

推奨：ほとんどの用途では Puppeteer を使用してください。すでにテストで Playwright を使用している場合は、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 時間に基づきます（有料プランのみ）。無料枠は 1 日あたり 10 分です。有料プランには月 10 時間分が含まれ、それを超えるとブラウザー 1 時間あたり $0.09、同時ブラウザー数が 10 を超える分について 1 つあたり $2.00 がかかります。

料金プラン、クォータの詳細、レート制限戦略、コスト最適化の手法については、references/pricing-and-limits.md を読み込んでください。

---

既知の問題の防止

このスキルは、文書化された 6 件の問題を防ぎます。重大なエラーの上位 3 件を以下に示します。

---

問題 #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 セレクター、または XPathEvaluator を使った page.evaluate() を使用します

解決策：

// ❌ 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：ブラウザーのバインディングが渡されていない ⚠️

エラー： "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 に渡してください

解決策：

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

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

---

Issue #3：ブラウザーのタイムアウト（60 秒）⚠️

エラー： 60 秒後にブラウザーが予期せず閉じる 出典： https://developers.cloudflare.com/browser-rendering/platform/limits/#note-on-browser-timeout 発生理由： デフォルトでは、非アクティブ状態が 60 秒続くとタイムアウトするため 予防策： keep_alive オプションを使用すると、最大 10 分まで延長できます

解決策：

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

注： 指定した時間内に devtools コマンドが実行されない場合、ブラウザーは閉じます。

---

その他の問題（4～6）

エラーの全一覧は、次の内容を含む references/common-errors.md を読み込んでください。：

• Issue #4：同時実行数の制限とレート制限
• Issue #5：ローカル開発時のリクエストサイズ制限
• Issue #6：ボット対策と WAF のバイパス方法

ページのクラッシュ、認証の問題、リソース読み込みエラー、デバッグ方法の解決策も記載されています。

---

本番環境チェックリスト

デプロイ前の重要項目：

• ✅ ブラウザーのバインディングと nodejs_compat フラグを設定
• ✅ try-finally によるクリーンアップ付きのエラー処理
• ✅ レート制限の確認と再試行ロジック
• ✅ パフォーマンス向上のためのセッション再利用
• ✅ 繰り返し実行する操作のための KV キャッシュ
• ✅ 入力検証（SSRF を防止）
• ✅ https://dash.cloudflare.com のモニタリングダッシュボード

本番環境向けのテンプレート、完全なエラー処理、モニタリング、セキュリティパターンについては、references/patterns.md を読み込んでください。

---

依存関係

必須： @cloudflare/[email protected]、[email protected]、@cloudflare/[email protected] 関連スキル： cloudflare-worker-base（Worker のセットアップ）、cloudflare-kv（キャッシュ）、cloudflare-workers-ai（AI によるスクレイピング）

---

公式ドキュメント

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

---

パッケージのバージョン（2025-11-27 確認済み）

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

代替（Playwright）：

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

---

トラブルシューティング

問題："Cannot read properties of undefined (reading 'fetch')"

解決策： ブラウザーのバインディングを puppeteer.launch() に渡します：

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

問題：XPath セレクターが機能しない

解決策： CSS セレクターを使用するか、XPathEvaluator を使って page.evaluate() を実行します（Issue #1 を参照）

問題：60 秒後にブラウザーが閉じる

解決策： keep_alive でタイムアウトを延長します：

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

問題：レート制限に達した

解決策： セッションを再利用し、タブを使用し、起動前に制限を確認します（Issue #4 を参照）

問題：ローカル開発で 1MB を超えるリクエストが失敗する

解決策： wrangler.jsonc でリモートバインディングを有効にします：

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

問題：Web サイトにボットとしてブロックされる

解決策： 回避できません。独自のゾーンの場合は、WAF のスキップルールを作成してください（Issue #6 を参照）

---

質問や問題がありますか？

1. 詳細な解決策については references/common-errors.md を確認してください
2. パフォーマンスの最適化については references/session-management.md を確認してください
3. wrangler.jsonc でブラウザーのバインディングが設定されていることを確認してください
4. 公式ドキュメントを確認してください：https://developers.cloudflare.com/browser-rendering/
5. nodejs_compat 互換性フラグが有効になっていることを確認してください