Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Puppeteer

最終更新 Markdown で表示Agent セットアップ

Puppeteer ↗ は、低レベルの DevTools プロトコルを抽象化し、Chrome / Chromium の操作とブラウジングセッションの自動化を簡単にする、よく使われる高レベル API です。スクリーンショットの作成、ページのクロール、Web アプリケーションのテストなどに使います。

Puppeteer は通常、DevTools ポート経由でローカルの Chrome または Chromium に接続します。詳細は Puppeteer API ドキュメントの Puppeteer.connect() メソッド ↗ を参照してください。

Workers チームは Puppeteer をフォークし、Workers の Browser Run API に接続するようパッチを当てています。接続後は、通常の環境と同じ Puppeteer API ↗ を使えます。

このバージョンはオープンソースで、Cloudflare の Puppeteer フォーク ↗ にあります。npm パッケージは npmjs ↗ の @cloudflare/puppeteer ↗ からインストールできます。

npm i -D @cloudflare/puppeteer

Worker で Puppeteer を使う

ブラウザバインディング を設定し、@cloudflare/puppeteer をインストールすると、Worker 内で Puppeteer を使えます。

import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		const browser = await puppeteer.launch(env.MYBROWSER);
		const page = await browser.newPage();
		await page.goto("https://example.com");
		const metrics = await page.metrics();
		await browser.close();
		return Response.json(metrics);
	},
};
import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
}

export default {
	async fetch(request, env): Promise<Response> {
		const browser = await puppeteer.launch(env.MYBROWSER);
		const page = await browser.newPage();
		await page.goto("https://example.com");
		const metrics = await page.metrics();
		await browser.close();
		return Response.json(metrics);
	},
} satisfies ExportedHandler<Env>;

このスクリプトは env.MYBROWSER ブラウザを 起動 ↗ し、新しいページ ↗ を開き、https://example.com/ ↗ に 移動 ↗ し、ページ読み込みの メトリクス ↗ を取得して、ブラウザを 閉じ ↗、メトリクスを JSON で返します。

Keep Alive

browser.close() を省略すると、ブラウザは開いたままになり、再接続して 再利用 できます。ただし既定では、1 分間操作がないと自動で閉じます。ミリ秒単位の keep_alive オプションで、このアイドル時間を最大 10 分まで延ばせます。

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

上記を使うと、操作がなくてもブラウザは最大 10 分間開いたままになります。

カスタム User-Agent を設定する

Puppeteer でカスタム User-Agent を指定するには、page.setUserAgent() メソッドを使います。対象サイトが User-Agent に応じて異なるコンテンツを返す場合に便利です。

await page.setUserAgent(
	"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
);

ヘッドフルモードでのローカルデバッグ（実験的）

wrangler dev または vite dev でローカル開発すると、Chrome は既定でヘッドレスモードで起動します。表示あり（headful）モードで起動するには、X_BROWSER_HEADFUL 環境変数を設定します。

X_BROWSER_HEADFUL=true npx wrangler dev

または Cloudflare Vite plugin を使う場合:

X_BROWSER_HEADFUL=true npx vite dev

ブラウザウィンドウが開き、Puppeteer の自動化をリアルタイムで確認できます。ナビゲーション、要素の選択、ページ操作のデバッグがしやすくなります。

要素の選択

Puppeteer には、ページ上の要素を選ぶ方法が複数あります。CSS セレクターは期待どおりに動作しますが、Workers ランタイムのセキュリティ制約により、XPath セレクターは使えません。

XPath セレクターの代わりに、CSS セレクターを使うか、page.evaluate() でブラウザコンテキスト内に XPath クエリを実行できます。

const innerHtml = await page.evaluate(() => {
	return (
		// @ts-ignore this runs on browser context
		new XPathEvaluator()
			.createExpression("/html/body/div/h1")
			// @ts-ignore this runs on browser context
			.evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE).singleNodeValue
			.innerHTML
	);
});

セッション管理

ブラウザセッションを扱いやすくするため、puppeteer に次のメソッドを追加しています。

開いているセッションを一覧する

puppeteer.sessions() は、現在実行中のセッションを一覧します。出力は次のようになります。

[
	{
		"connectionId": "2a2246fa-e234-4dc1-8433-87e6cee80145",
		"connectionStartTime": 1711621704607,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"sessionId": "565e05fb-4d2a-402b-869b-5b65b1381db7",
		"startTime": 1711621703808
	}
]

セッション 478f4d7d-e943-40f6-a414-837d3736a1dc にはアクティブな Worker 接続（connectionId=2a2246fa-e234-4dc1-8433-87e6cee80145）があり、セッション 565e05fb-4d2a-402b-869b-5b65b1381db7 は空きです。接続がアクティブなあいだ、ほかの Worker はそのセッションに接続できません。

最近のセッションを一覧する

puppeteer.history() は、開いているセッションと閉じたセッションの両方を含む最近のセッションを一覧します。現在の使用状況を把握するのに便利です。

[
	{
		"closeReason": 2,
		"closeReasonText": "BrowserIdle",
		"endTime": 1711621769485,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"closeReason": 1,
		"closeReasonText": "NormalClosure",
		"endTime": 1711123501771,
		"sessionId": "2be00a21-9fb6-4bb2-9861-8cd48e40e771",
		"startTime": 1711123430918
	}
]

セッション 2be00a21-9fb6-4bb2-9861-8cd48e40e771 はクライアントが browser.close() で明示的に閉じ、セッション 478f4d7d-e943-40f6-a414-837d3736a1dc は最大アイドル時間に達して閉じました（制限 を確認してください）。

ダッシュボードでも、少し遅れて同じ情報を確認できます。

有効な制限

puppeteer.limits() は、現在有効な制限を一覧します。

{
	"activeSessions": [
		{ "id": "478f4d7d-e943-40f6-a414-837d3736a1dc" },
		{ "id": "565e05fb-4d2a-402b-869b-5b65b1381db7" }
	],
	"allowedBrowserAcquisitions": 1,
	"maxConcurrentSessions": 2,
	"timeUntilNextAllowedBrowserAcquisition": 0
}
  • activeSessions は、現在開いているセッションの ID を一覧します
  • maxConcurrentSessions は、同時に開けるブラウザ数を定義します
  • allowedBrowserAcquisitions は、適用中のレート 制限 に従い、新しいブラウザセッションを開けるかどうかを示します
  • timeUntilNextAllowedBrowserAcquisition は、次のブラウザを起動できるまでの待ち時間です。

Puppeteer API

完全な Puppeteer API は、Cloudflare の Puppeteer フォーク ↗ にあります。

役に立ちましたか？