Skip to content

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

Workers で最適化する

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

バインディング は、Worker を Developer Platform 上の外部リソース（Images、R2 バケット、KV 名前空間 など）に接続します。

Images バインディングを使うと、Worker 内で画像の最適化と加工を直接行えます。URL インターフェース では画像を URL 経由で公開する必要がありますが、バインディングは生の画像バイトを扱えます。画像は Images、R2、fetch() のレスポンス、リクエスト本文など、任意のソースから渡せます。

Images バインディングでは、次のことができます。

  • Images または R2 に保存した画像を、公開 URL 経由で取得せず、バイトを直接渡して最適化します。
  • 画像をリサイズし、透かしを重ね、結合した出力を再度リサイズして最終結果にする処理を、1 つの操作チェーンで完結します。
  • 最適化パラメーターの適用順を制御します。URL インターフェースでは、最適化パラメーターの適用順は固定です。

バインディングは、Worker 向けの Cloudflare ダッシュボード、またはプロジェクトディレクトリの 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 — テキストのフォントを設定します。カスタムの TrueType（.ttf）、OpenType（.otf）、Web Open（.woff と .woff2）フォントファイル（最大 20 MB）を指す url プロパティを持つオブジェクトを受け取ります。フォントの取得または解析に失敗すると、リクエストはエラーを返します。
  • 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)

指定した出力オプションで最終画像を生成します。Worker から画像を返すには、結果に対して .response() を呼びます。

次のオプションを受け取れます。

  • 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)

Worker から返せる Response を返します。

次のオプションを受け取れます。

  • headers — Response に追加するヘッダーを HeadersInit として設定します。Response を作り直さず、Cache-Control などのヘッダーを直接設定できます。

Content-Type は常に出力フォーマットから設定され、上書きできません。

.info(stream)

format、fileSize、width、height など、画像に関する情報を出力します。

ローカルで Images バインディングを使う

Images API は、Workers 向けコマンドラインインターフェースの Wrangler を通じてローカル開発で使えます。ローカル開発で Images バインディングを使っても、使用量の課金は発生しません。

Wrangler は Images API の 2 つのバージョンに対応しています。

  • Images API で使える全機能に対応する高精度版です。Cloudflare が本番でグローバルに実行しているものと同じバージョンです。
  • リサイズや回転など一部の機能だけに対応する、低精度のオフライン版です。

Images の低精度版を試すには、wrangler dev を実行します。

npx wrangler dev

現在、このバージョンが対応しているのは width、height、rotate、format だけです。

Images の高精度リモート版を試すには、--remote フラグを使います。

npx wrangler dev --remote

Workers Vitest 連携 でテストする場合、テスト中に Cloudflare API へアクセスしないよう、デフォルトでは低精度のオフライン版が使われます。

役に立ちましたか？