跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

使用 Workers 优化

最后更新 查看 MarkdownAgent 设置

绑定(binding) 将您的 Worker 连接到 Developer Platform 上的外部资源,如 Images、R2 存储桶 或 KV 命名空间。

Images 绑定让您直接在 Worker 中优化和处理图像。与需要图像通过 URL 可访问的 URL 接口 不同,绑定使用原始图像字节。您可以从任何源传递图像,包括 Images、R2、fetch() 响应或请求体。

使用 Images 绑定,您可以:

  • 通过直接传递字节优化存储在 Images 或 R2 中的图像,而不是通过公共 URL 获取。
  • 调整图像大小、叠加水印,然后将组合输出调整为最终结果——全部在单个操作链中完成。
  • 控制优化参数的操作顺序。使用 URL 接口时,优化参数遵循固定的操作顺序。

绑定可以在 Cloudflare 仪表板中为 Worker 配置,或在项目目录的 Wrangler 配置文件中配置。

设置

Images 绑定按 Worker 启用。

您可以在 Worker 项目目录的 Wrangler 配置文件中定义变量。这些变量在运行时绑定到外部资源,然后您可以通过此变量与它们交互。

要将 Images 绑定到 Worker,请在 Wrangler 配置文件末尾添加以下内容:

{
	"images": {
		"binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
	},
}
[images]
binding = "IMAGES"

在 Worker 代码中,使用 env.IMAGES.input() 构建可以操作图像的对象(作为 ReadableStream 传递)。

方法

操作从源方法开始——图像使用 .input(),文本使用 .text()——并以 .output() 结束。两种源方法都返回优化句柄,可用于链式调用 .transform() 和 .draw()。

.input(stream)

为图像创建优化句柄。接受来自任何源(包括 Images、R2、fetch() 响应或请求体)的最多 20 MB 图像字节。

返回可用于链式调用 .transform()、.draw() 和 .output() 的句柄。

export default {
	async fetch(request, env) {
		const imageURL = "https://example.com/photo.jpg";

		const response = await fetch(imageURL);
		if (!response.ok || !response.body) {
			return new Response("Upstream fetch failed", { status: 502 });
		}

		return (
			await env.IMAGES.input(response.body)
				.transform({ width: 800 })
				.output({ format: "image/webp" })
		).response();
	},
};
export default {
	async fetch(request, env) {
		const imageURL = "https://example.com/photo.jpg";

		const response = await fetch(imageURL);
		if (!response.ok || !response.body) {
			return new Response("Upstream fetch failed", { status: 502 });
		}

		return (
			await env.IMAGES.input(response.body)
				.transform({ width: 800 })
				.output({ format: "image/webp" })
		).response();
	},
};

.text(content, options)

为文本创建优化句柄。Cloudflare 使用 options 将 content 栅格化为图像。图像尺寸由文本字符串及其样式决定。

返回可用于链式调用 .transform()、.draw() 和 .output() 的句柄。将该句柄传给 .draw() 可将文本叠加到基础图像上,或直接对其调用 .output() 以生成带透明背景的独立图像。

content

设置要渲染的文本字符串。此参数为必填。

options

设置文本的样式选项。这些选项同时适用于绑定中的 .text() 方法,以及在 cf.image 的 draw 数组中绘制叠加时的 text 条目。

接受以下选项:

  • font — 设置文本字体。接受带有 url 属性的对象,该属性指向自定义 TrueType(.ttf)、OpenType(.otf)、Web Open(.woff 和 .woff2)字体文件,最大 20 MB。如果无法获取或解析字体,则请求返回错误。
  • color — 设置文本填充颜色。接受 HEX 代码、CSS 颜色名称或 CSS 颜色函数。默认为 #000000(黑色)。
  • size — 设置字体大小(像素)。默认为 12。

渲染后的文本最多 1,000 个字符,最大尺寸为 4096 x 4096 像素。如果文本叠加超出这些限制,则请求返回错误。

要在图像上绘制文本,请参阅绘制叠加和水印。

.transform(options)

对图像应用优化参数,如 width、height 或 blur。您可以链式调用多个 .transform() 来控制参数应用的顺序。

有关参数的完整列表,请参阅功能。

以下示例展示如何通过获取图像字节来调整存储在 Images 中的图像大小:

// Get the raw bytes of a hosted image
const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();
if (!bytes) {
	return new Response("Not found", { status: 404 });
}

// Resize and transcode the image
const response = (
	await env.IMAGES.input(bytes)
		.transform({ width: 400 })
		.output({ format: "image/webp" })
).response();

return response;
// Get the raw bytes of a hosted image
const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();
if (!bytes) {
	return new Response("Not found", { status: 404 });
}

// Resize and transcode the image
const response = (
	await env.IMAGES.input(bytes)
		.transform({ width: 400 })
		.output({ format: "image/webp" })
).response();

return response;

.draw(image, options)

在另一张图像上绘制叠加图像。

叠加可以是图像字节流或另一个 .input() 链。您可以在此方法内传递子 .transform() 函数,在绘制之前调整或处理叠加图像。

接受 opacity、repeat、边(left、right、top、bottom)和 composite。有关完整的绘制选项和示例,请参阅绘制叠加和水印。

.output(options)

使用指定的输出选项生成最终图像。返回一个结果,您可以对其调用 .response(),以便从 Worker 返回该图像。

接受以下选项:

  • format — 以支持的格式(如 AVIF、WebP 或 JPEG)编码图像。此方法是必需的——没有默认输出格式。
  • quality — 指定 JPEG、WebP 和 AVIF 格式的输出质量,以固定值或感知质量级别表示。
  • anim — 指定是否保留动画帧。设置 anim:false 将动画转换为静态图像。
const response = (
	await env.IMAGES.input(stream)
		.transform({ rotate: 90 })
		.transform({ width: 128 })
		.transform({ blur: 20 })
		.output({ format: "image/avif" })
).response();

return response;
const response = (
	await env.IMAGES.input(stream)
		.transform({ rotate: 90 })
		.transform({ width: 128 })
		.transform({ blur: 20 })
		.output({ format: "image/avif" })
).response();

return response;

.response(options)

返回一个 Response,您可以从 Worker 中返回它。

接受以下选项:

  • headers — 以 HeadersInit 形式在 Response 上设置的额外标头。用此选项直接设置 Cache-Control 或其他标头,而无需重新构建 Response。

Content-Type 始终根据输出格式设置,且无法覆盖。

.info(stream)

输出有关图像的信息,如 format、fileSize、width 和 height。

在本地与 Images 绑定交互

Images API 可以通过 Wrangler(Workers 的命令行界面)在本地开发中使用。在本地开发中使用 Images 绑定不会产生使用费用。

Wrangler 支持两个不同版本的 Images API:

  • 支持 Images API 所有可用功能的高保真版本。这与 Cloudflare 在全球生产环境中运行的版本相同。
  • 仅支持部分功能(如调整大小和旋转)的低保真离线版本。

要测试 Images 的低保真版本,您可以运行 wrangler dev:

npx wrangler dev

目前,此版本仅支持 width、height、rotate 和 format。

要测试 Images 的高保真远程版本,您可以使用 --remote 标志:

npx wrangler dev --remote

使用 Workers Vitest 集成 测试时,默认使用低保真离线版本,以避免在测试中调用 Cloudflare API。

这篇文档对您有帮助吗?