よくある質問

Browser Run（旧称 Browser Rendering）について、よくある質問への回答をまとめています。

料金については 料金 FAQ を参照してください。 利用上限については 制限 FAQ を参照してください。 探している回答が見つからない場合は、Discord ↗ に参加してください。

このエラーは、Puppeteer の起動時にブラウザーバインディングが渡されていないときに起きることが多いです。解消するには、puppeteer.launch にブラウザーバインディングを渡します。

このエラー（Unable to create new browser: code: 429: message: Browser time limit exceeded for today）は、Workers Free プランの 1 日あたりのブラウザーインスタンス上限に達したことを示します。Workers Free プランのアカウントは、1 日あたり 10 分のブラウザー利用に制限されます。上限を超えると、次の UTC 日になるまで、新規作成は 429 エラーを返します。

解消するには、Workers Paid プランにアップグレード します。Paid プランでは 1 日あたり 10 分を超えて使え、制限 も高くなります。最近アップグレードしたのにこのエラーが出る場合は、Worker を再デプロイして、新しいプランに利用量が正しく紐づいているか確認してください。

422 Unprocessable Entity は、サイト側の問題で Browser Run が操作を完了できなかったときに出ることが多いです。

次のような場合に起きることがあります。

• レンダリング中にウェブサイトがメモリを使いすぎた。
• 操作完了前にページがクラッシュした、またはエラーを返した。
• ページ読み込み、要素読み込み、操作のいずれかの タイムアウト上限 を超えた。

多くの場合、原因はタイムアウトです。タイマーの種類と上限は Quick Actions のタイムアウトリファレンス で確認できます。

スクリーンショット、PDF、スクレイプ結果に、通常のブラウザーでは見える要素が欠けている場合、Browser Run が出力を取得する前にページの読み込みが終わっていない可能性が高いです。

JavaScript が多いページやシングルページアプリケーション（SPA）は、最初の HTML 解析のあとに動的にコンテンツを読み込むことがよくあります。デフォルトでは Browser Run は domcontentloaded を待ちます。このイベントは、JavaScript による描画が終わる前に発火します。

対処するには、goToOptions.waitUntil に次のいずれかを指定します。

Quick Actions の例:

{
	"url": "https://example.com",
	"goToOptions": {
		"waitUntil": "networkidle2"
	}
}

それでも内容が欠ける場合は、次を試します。

• waitForSelector で、特定の要素が表示されてから取得する。
• 読み込みが遅いページでは goToOptions.timeout を伸ばす（最大 60 秒）。
• 認証が必要か、ボット向けに別の内容を返していないかを確認する。

全体のリファレンスは Quick Actions のタイムアウト を参照してください。

ローカルでブラウザーを動かす方法は、開発や小規模な作業には向きます。本番の負荷には実用上の限界があります。

Browser Run では、ブラウザーセッションは Cloudflare のインフラストラクチャ上で動きます。ローカルマシンがなくても自動化を実行できます。Chrome のインストールを維持する必要もなく、VM を常時起動しておく必要もありません。セッションは必要なときに起動し、完了したら終了します。

Cloudflare Queues で URL を非同期にまとめて処理することもできます。キュー基盤を自分で管理せずに、大規模なクロールができます。

ブラウザーセッションは Cloudflare のグローバルネットワーク上で、受信リクエストの近くに開きます。Browser Run は Workers バインディング なので、Durable Objects、Queues、その他の Cloudflare 開発者向けプラットフォームと直接連携できます。

まだです。ローカル開発には現在、次の制限があります。

• 1 MB を超えるリクエストは未対応です。

ローカル開発では、自動化スクリプトを目で確認するために、Chrome を表示あり（headful）モードで動かすこともできます（実験的）。開発サーバーを起動する前に、環境変数 X_BROWSER_HEADFUL を設定します。

X_BROWSER_HEADFUL=true npx wrangler dev

レンダリング対象のページに認証が必要な場合は、次のいずれかの方法で資格情報を渡せます。これらのパラメーターは、すべての Quick Actions エンドポイントで使えます。

HTTP Basic Auth:

{
	"authenticate": {
		"username": "user",
		"password": "pass"
	}
}

Cookie ベースの認証:

{
	"cookies": [
		{
			"name": "session_id",
			"value": "abc123",
			"domain": "example.com",
			"path": "/",
			"secure": true,
			"httpOnly": true
		}
	]
}

トークンベースの認証:

{
	"setExtraHTTPHeaders": {
		"Authorization": "Bearer your-token"
	}
}

3 つの方法の動作する完全な例は、認証済みページのスクリーンショットを取得する を参照してください。

はい。Browser Run のリクエストは、Cloudflare によって常にボットトラフィックとして識別されます。Cloudflare はボット保護をデフォルトでは強制しません。適用するかどうかはお客様の選択です。

自ゾーンをスキャンしたい場合で、ボット保護の設定に邪魔されずに Browser Run にサイトへアクセスさせたいときは、WAF のスキップルールを作成して Browser Run を許可リストに追加 できます。

自分のウェブサイトで Browser Run を許可リストに追加するには、Enterprise プランが必要です。WAF カスタムルールで Bot Management のフィールドを使うためです。

Browser Run は方式ごとに異なる bot detection ID を使います。許可したい方式に対応する ID を使います。

しません。Browser Run のリクエストは Cloudflare のグローバルネットワークから発信され、リクエスト単位の IP ローテーションは設定できません。レンダリングトラフィックはすべて Cloudflare の IP レンジから発信されます。リクエストには cf-biso-request-id や cf-biso-devtools などの 自動ヘッダー が付き、オリジンサーバーが識別できます。

1 セッションあたりのリクエスト数に固定の上限はありません。利用可能なコンピュートとメモリの範囲内であれば、1 つのブラウザーで複数のリクエストを処理できます。

使えます。ウェブページや PDF に、事前インストールされていないフォントが必要な場合は、レンダリング時に addStyleTag でカスタムフォントを読み込めます。Quick Actions、Puppeteer、Playwright で使えます。手順と例は カスタムフォント を参照してください。

同時実行の 制限 に達している場合や、同時ブラウザー利用を最適化したい場合は、次のヒントを参考にしてください。

• タブまたは共有ブラウザーで最適化する: タスクごとに新しいブラウザーを起動する代わりに、同じブラウザーインスタンスで複数のタブを開く、または複数の操作を実行することを検討してください。
• セッションを再利用する: 毎回新しいブラウザーを起動せずセッションを再利用すると、構成を最適化し、起動時間を短縮できます。テストの分離（クリーンな環境に依存するテストなど）を維持したい場合は、Cookie とキャッシュをほかのセッションから分離する シークレット（incognito）ブラウザーコンテキスト ↗ の利用をおすすめします。

それでも同時実行の制限に達する場合は、上限の引き上げを申請 ↗ できます。

ほとんどのワークロードでは、タスクごとに新しいブラウザーを起動せず、既存のブラウザーセッションを再利用して新しいタブを開きます。Browser Run は、ブラウザーインスタンスを 同時ブラウザー数 と 新規ブラウザーインスタンスのレート の制限に計上します。既存セッション内のタブは、どちらの制限にも計上されません。セッションの再利用は、新しいブラウザー起動のコールドスタートコストも避けられます。

1 つのブラウザーで多数のタブを動かせますが、すべてのタブは同じブラウザープロセスとメモリを共有します。重いページ（大きな JavaScript バンドル、メディア、複雑な DOM など）はタブあたりのメモリ使用量が大きいため、同じブラウザーでタブを開きすぎるとクラッシュすることがあります。安全なタブ数は、ワークロードを試して決めてください。軽いページなら数十タブでも問題ないことがあります。重いページでは数タブに抑えます。

セッションは再利用しつつタスク間の分離が必要な場合は、シークレット（incognito）ブラウザーコンテキストを使います。incognito コンテキストは Cookie、ローカルストレージ、キャッシュを互いに、およびデフォルトコンテキストから分離します。同じブラウザー内のタブで別タスクを動かしても、データが漏れにくくなります。

import puppeteer from "@cloudflare/puppeteer";

const browser = await puppeteer.connect(env.MYBROWSER, sessionId);
// or await puppeteer.launch(env.MYBROWSER);

const context = await browser.createBrowserContext();
const page = await context.newPage();

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

const browser = await connect(env.BROWSER, sessionId);
// or use the browser returned by acquire()

const context = await browser.newContext();
const page = await context.newPage();

新しいブラウザーを開くのは、プロセス単位の完全な分離が必要なとき、別のブラウザー設定が必要なとき、またはブラウザーが不安定になったあとだけにします。スクリーンショット、スクレイプ、クロールの自動化では、セッションとタブの再利用が適切であることが多いです。Quick Actions はセッションとタブを自動管理するため、再利用を自分で扱う必要はありません。

Quick Actions（/crawl エンドポイント を除く）、Puppeteer、Playwright、CDP では、Cloudflare はコンテンツを一時的に処理します。お客様が送信した HTML や、PDF・スクリーンショットなどの生成結果は、レンダリングに必要な範囲を超えて保持しません。応答を返したあと、レンダリング環境からすぐ破棄します。

セッションを超えてデータを保持する例外は次の 2 つです。

• Crawl エンドポイント: /crawl Quick Actions エンドポイント はジョブを非同期で実行します。ジョブ結果（クロールしたページの HTML、Markdown、JSON）は完了後 14 日間保存され、その後削除されます。クロールジョブの最大実行時間は 7 日です。
• セッション録画: Puppeteer、Playwright、CDP セッションは、オプトインの セッション録画 に対応しています。有効にすると、DOM の変更、マウスとキーボードのイベント、ページ遷移が構造化 JSON イベントとして記録され、30 日間保持されます。入力欄の内容はデフォルトでマスクされます。録画は ダッシュボード と API から参照でき、保持期間後に自動削除されます。

Quick Actions（/crawl エンドポイント を除く）では、生成コンテンツはデフォルトで 5 秒間キャッシュされます（cacheTTL パラメーターで最大 1 日まで設定できます。0 にするとキャッシュを無効にします）。このキャッシュは、同じアカウントによる同じ URL への繰り返しリクエストを防ぎます。お客様が送信した HTML 自体はキャッシュされません。

Puppeteer、Playwright、CDP ではキャッシュは使いません。コンテンツはレンダリング中だけメモリ上にあり、応答を返した直後に破棄されます。

/crawl エンドポイント では、クロールジョブの結果はすべて、完了後 14 日間 R2 に保存されます。