Skip to content

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

はじめに

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

Cloudflare Browser Run（旧称 Browser Rendering）では、ヘッドレスブラウザーをプログラムから操作できます。スクリーンショットの取得、PDF の生成、ブラウザーの自動化などができます。このガイドでは、適切な連携方法を選び、最初のプロジェクトを始めます。

Browser Run の連携方法は、次の 2 種類です。

  • Quick Actions: スクリーンショット、PDF、スクレイピングなど、状態を持たない単純なブラウザー作業です。コードのデプロイは不要です。
  • ブラウザーセッション: Puppeteer、Playwright、CDP、Stagehand でブラウザーを直接操作します。Cloudflare Workers 内にデプロイするか、CDP 経由で任意の環境から接続します。
用途 推奨 理由
単純なスクリーンショット、PDF、スクレイピング Quick Actions コードのデプロイ不要。HTTP リクエスト 1 回で完結
ブラウザー自動化 Playwright、Puppeteer、または CDP スクリプトでブラウザーを完全に制御できる
既存スクリプトの移植 Puppeteer、Playwright、または CDP 標準ライブラリからのコード変更が少ない
AI によるデータ抽出 JSON エンドポイント 自然言語プロンプトで構造化データを取得
サイト全体のクロール Crawl エンドポイント 複数ページのコンテンツを非同期で抽出
AI エージェントによるブラウジング Playwright MCP または MCP クライアント付き CDP LLM が MCP 経由でブラウザーを操作
耐障害性の高いスクレイピング Stagehand AI がセレクターではなく意図で要素を探す
任意の環境からの直接操作 CDP ローカルマシン、CI/CD、外部サーバーから WebSocket で接続

Quick Actions

Quick Actions は REST API から使うか、Cloudflare Worker のブラウザーバインディングから直接使えます。

前提条件

例: スクリーンショットを取得する

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com"
  }' \
  --output "screenshot.png"

前提条件

例: Worker からスクリーンショットを取得する

1. Worker プロジェクトを作成する

次のコマンドを実行し、browser-quick-action という名前の新しい Worker プロジェクトを作成します。

npm create cloudflare@latest -- browser-quick-action

セットアップでは、次のオプションを選びます。

  • What would you like to start with? では、Hello World example を選びます。
  • Which template would you like to use? では、Worker only を選びます。
  • Which language do you want to use? では、TypeScript を選びます。
  • Do you want to use git for version control? では、Yes を選びます。
  • Do you want to deploy your application? では、No を選びます（デプロイ前にいくつか変更します）。

2. ブラウザーバインディングを設定する

Wrangler 設定ファイル に、ブラウザー バインディング を追加します。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "browser-quick-action",
  "main": "src/index.ts",
  // Set this to today's date
  "compatibility_date": "2026-09-20",
  "browser": {
    "binding": "BROWSER"
  }
}
name = "browser-quick-action"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-20"

[browser]
binding = "BROWSER"

3. Worker のコードを書く

src/index.ts の内容を次のコードに置き換えます。

export default {
	async fetch(request, env) {
		return await env.BROWSER.quickAction("screenshot", {
			url: "https://example.com",
		});
	},
};
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("screenshot", {
			url: "https://example.com",
		});
	},
} satisfies ExportedHandler<Env>;

この Worker はブラウザーバインディングを使い、example.com のスクリーンショットを撮影して、画像をレスポンスとしてそのまま返します。

4. テストする

npx wrangler dev --remote を実行し、ローカルで Worker をテストします。

ローカル URL を開き、スクリーンショットを確認します。

5. デプロイする

npx wrangler deploy を実行し、Worker を Cloudflare のグローバルネットワークにデプロイします。

ほかの Quick Actions エンドポイントには次があります。

Quick Actions エンドポイント の一覧も確認してください。

ブラウザーセッション

前提条件

  1. Cloudflare アカウント ↗ に登録します。
  2. Node.js ↗ をインストールします。

Node.js のバージョンマネージャー

権限の問題を避け、Node.js のバージョンを切り替えられるよう、Volta ↗ や nvm ↗ などの Node バージョンマネージャーを使います。このガイドの後半で説明する Wrangler には、Node バージョン 16.17.0 以降が必要です。

例: URL に移動し、スクリーンショットを取得して KV に保存する

1. Worker プロジェクトを作成する

Cloudflare Workers は、インフラの設定や運用なしに、新しいアプリケーションの作成や既存アプリの拡張ができるサーバーレス実行環境です。Worker アプリケーションは、ヘッドレスブラウザーとやり取りしてスクリーンショット撮影などの操作を行うコンテナになります。

次のコマンドで、browser-worker という名前の新しい Worker プロジェクトを作成します。

npm create cloudflare@latest -- browser-worker

セットアップでは、次のオプションを選びます。

  • What would you like to start with? では、Hello World example を選びます。
  • Which template would you like to use? では、Worker only を選びます。
  • Which language do you want to use? では、JavaScript / TypeScript を選びます。
  • Do you want to use git for version control? では、Yes を選びます。
  • Do you want to deploy your application? では、No を選びます（デプロイ前にいくつか変更します）。

2. Puppeteer をインストールする

browser-worker ディレクトリで、Cloudflare の Puppeteer フォーク をインストールします。

npm i -D @cloudflare/puppeteer

3. KV 名前空間を作成する

Browser Run は、ほかの開発者向け製品と組み合わせて使えます。クロールしたページやアセットを保存する リレーショナルデータベース や R2 バケット、ブラウザーインスタンスを生かしたまま複数リクエストで共有する Durable Object、ジョブを非同期で処理する Queues が必要になることがあります。

この例では、スクリーンショットのキャッシュに KV ストア を使います。

本番用と開発用の 2 つの名前空間を作成します。

npx wrangler kv namespace create BROWSER_KV_DEMO
npx wrangler kv namespace create BROWSER_KV_DEMO --preview

次の手順で使うため、ID を控えておきます。

4. Wrangler 設定ファイルを構成する

browser-worker プロジェクトの Wrangler 設定ファイル に、ブラウザー バインディング と Node.js 互換フラグ を追加します。バインディングを使うと、Worker は Cloudflare 開発者プラットフォーム上のリソースと連携できます。ブラウザーの binding 名は自分で決めます。このガイドでは MYBROWSER を使います。ブラウザーバインディングは Worker とヘッドレスブラウザーの通信を可能にし、スクリーンショット撮影、PDF 生成などの操作ができます。

Wrangler 設定ファイル を、Browser Run API バインディングと作成した KV 名前空間で更新します。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "browser-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"compatibility_flags": ["nodejs_compat"],
	"browser": {
		"binding": "MYBROWSER"
	},
	"kv_namespaces": [
		{
			"binding": "BROWSER_KV_DEMO",
			"id": "22cf855786094a88a6906f8edac425cd",
			"preview_id": "e1f8b68b68d24381b57071445f96e623"
		}
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "browser-worker"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-09-20"
compatibility_flags = [ "nodejs_compat" ]

[browser]
binding = "MYBROWSER"

[[kv_namespaces]]
binding = "BROWSER_KV_DEMO"
id = "22cf855786094a88a6906f8edac425cd"
preview_id = "e1f8b68b68d24381b57071445f96e623"

5. コード

src/index.js を、次の Worker コードで更新します。

import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = await page.screenshot();
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
};

src/index.ts を、次の Worker コードで更新します。

import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
	BROWSER_KV_DEMO: KVNamespace;
}

export default {
	async fetch(request, env): Promise<Response> {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img: Buffer;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = (await page.screenshot()) as Buffer;
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
} satisfies ExportedHandler<Env>;

この Worker は Puppeteer でブラウザーを起動し、新しいページを開き、url パラメーターの場所へ移動してスクリーンショットを撮影します。スクリーンショットを KV に保存し、ブラウザーを閉じて、JPEG 画像として返します。

Worker が本番で動いている場合は、本番用の KV 名前空間にスクリーンショットを保存します。wrangler dev を実行している場合は、開発用の KV 名前空間に保存します。

同じ url が再度リクエストされた場合は、期限切れでなければ KV のキャッシュを使います。

6. テスト

Worker をローカルでテストするには、npx wrangler dev を実行します。

最初のスクリーンショットをテストするには、次の URL を開きます。

<LOCAL_HOST_URL>/?url=https://example.com

7. デプロイ

Worker を Cloudflare のグローバルネットワークへデプロイするには、npx wrangler deploy を実行します。

最初のスクリーンショットを撮影するには、次の URL を開きます。

<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?url=https://example.com

次のステップ

機能の要望や不具合があれば、Discord の Cloudflare Developers コミュニティ ↗ から Cloudflare チームに直接フィードバックを送れます。

役に立ちましたか？