部署 Browser Run Worker

按照本指南，你将创建一个使用 Browser Run API 从网页截取屏幕截图的 Worker。这是浏览器自动化的常见用例。

注册 Cloudflare 账户 ↗。
安装 Node.js ↗。

Node.js 版本管理器

使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器，以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。

1. 创建 Worker 项目

Cloudflare Workers 提供无服务器执行环境，可创建新应用或扩展现有应用，无需配置或维护基础设施。Worker 应用是与无头浏览器交互的容器，可执行截图等操作。

运行以下命令创建名为 browser-worker 的新 Worker 项目：

npm create cloudflare@latest -- browser-worker

yarn create cloudflare browser-worker

pnpm 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

yarn add -D @cloudflare/puppeteer

pnpm add -D @cloudflare/puppeteer

bun add -d @cloudflare/puppeteer

3. 创建 KV 命名空间

Browser Run 可与其他开发者产品配合使用。你可能需要 D1 关系型数据库、用于归档爬取页面和资源的 R2 存储桶、用于保持浏览器实例存活并在多个请求间共享的 Durable Objects，或用于异步处理任务的 Queues。

本示例使用 KV 存储缓存截图。

创建两个命名空间，分别用于生产和开发。

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

记下 ID，供下一步使用。

4. 配置 Wrangler 配置文件

通过添加 browser 绑定（binding）和 Node.js 兼容性标志来配置 browser-worker 项目的 Wrangler 配置文件。绑定使 Worker 能够与 Cloudflare 开发者平台上的资源交互。browser binding 名称由你设定，本指南使用 MYBROWSER。browser 绑定使 Worker 与无头浏览器通信，可执行截图、生成 PDF 等操作。

使用 Browser Run API 绑定和已创建的 KV 命名空间更新 Wrangler 配置文件：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "browser-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"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-17"
compatibility_flags = [ "nodejs_compat" ]

[browser]
binding = "MYBROWSER"

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

5. 代码

用以下 Worker 代码更新 src/index.js：

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

用以下 Worker 代码更新 src/index.ts：

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. 测试

运行 npx wrangler dev 在本地测试 Worker。

要测试首次截图，访问以下 URL：

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

7. 部署

运行 npx wrangler deploy 将 Worker 部署到 Cloudflare 全球网络。

要获取首次截图，访问以下 URL：

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