← Browser Run / browser-run

Начало работы

Cloudflare Browser Run (ранее Browser Rendering) позволяет программно управлять headless-браузером: делать снимки экрана, создавать PDF-файлы и выполнять другие автоматизированные задачи в браузере. Это руководство поможет вам выбрать подходящий способ интеграции и приступить к работе над первым проектом.

Browser Run предлагает два типа методов интеграции:

• Быстрые действия: простые, не сохраняющие состояние задачи браузера, такие как скриншоты, PDF и скрапинг. Развёртывание кода не требуется.
• Browser Sessions: прямое управление браузером через Puppeteer, Playwright, CDP, или Stagehand. Разверните в Cloudflare Workers или подключайтесь из любой среды через CDP.

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"

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

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

name = "browser-quick-action"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[browser]
binding = "BROWSER"

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

К другим эндпоинтам Quick Actions относятся:

• Получение HTML
• Создание PDF
• Сканирование веб-контента

Ознакомьтесь с полным списком Конечные точки Quick Actions.

1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗.
2. Установка Node.js ↗.

Cloudflare Workers предоставляет бессерверную среду выполнения, которая позволяет создавать новые приложения или дополнять существующие без настройки и обслуживания инфраструктуры. Ваше Worker-приложение служит контейнером для взаимодействия с headless-браузером и выполнения таких действий, как создание скриншотов.

Создайте новый проект Worker с именем browser-worker выполнив:

npm create cloudflare@latest -- browser-worker

Для настройки выберите следующие параметры:

• Для С чего вы хотите начать?, выберите Hello World example.
• Для Какой шаблон вы хотите использовать?, выберите Worker only.
• Для Какой язык вы хотите использовать?, выберите JavaScript / TypeScript.
• Для Хотите использовать git для контроля версий?, выберите Yes.
• Для Хотите развернуть приложение?, выберите No (мы внесём некоторые изменения перед развёртыванием).

В вашем browser-worker директории установите пакет Cloudflare форк Puppeteer:

npm i -D @cloudflare/puppeteer

Browser Run можно использовать вместе с другими продуктами для разработчиков. Вам может понадобиться реляционная база данных, Бакет R2 чтобы архивировать просканированные страницы и ресурсы, Durable Object чтобы экземпляр браузера оставался активным и использовался несколькими запросами, или Queues чтобы обрабатывать ваши задания асинхронно.

В этом примере мы будем использовать Хранилище KV чтобы кэшировать скриншоты.

Создайте два пространства имён: одно для продакшена и одно для разработки.

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

Запишите идентификаторы (ID) для следующего шага.

Настройте свой browser-worker проекта конфигурационный файл Wrangler добавив привязку browser привязка и Флаг совместимости с Node.js. Привязки позволяют вашим Workers взаимодействовать с ресурсами платформы разработчика Cloudflare. Ваш браузер binding задаётся вами, в этом руководстве используется имя MYBROWSER. Привязки браузера обеспечивают взаимодействие между Worker и headless-браузером, что позволяет выполнять такие действия, как создание снимка экрана, генерация 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-08-28",
	"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-08-28"
compatibility_flags = [ "nodejs_compat" ]

[browser]
binding = "MYBROWSER"

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

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");
		}
	},
};

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, если она ещё не устарела.

Запустите npx wrangler dev чтобы протестировать Worker локально.

Чтобы проверить создание первого снимка экрана, перейдите по следующему URL-адресу:

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

Запустите npx wrangler deploy чтобы развернуть Worker в глобальной сети Cloudflare.

Чтобы сделать первый снимок экрана, перейдите по следующему URL-адресу:

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

• Ознакомьтесь со всеми Конечные точки Quick Actions
• Попробуйте Playwright MCP
• Подключайтесь из любого окружения с помощью CDP
• Подробнее о Browser Run ограничения и цены

Если у вас есть пожелания по функциям или вы заметили ошибку, поделитесь отзывом напрямую с командой Cloudflare, присоединившись к Сообщество разработчиков Cloudflare в Discord ↗.