CDN を使った画像最適化パイプラインの構築
埋め込みの公開画像から三つの WebP リソースを生成し、その中から画像を選択する HTML を配信する Worker を一つ構築します。デコード後の画像をローカルで確認してから、Workers Cache を有効にして同じコードをデプロイし、繰り返しリクエストが実際にキャッシュにヒットするか検証できます。
画像 CDN の仕組み
画像パイプラインには、変換と配信の両方が必要です。この例では、Images binding が Worker 内で生の画像バイト列をリサイズします。Workers Cache は、その Worker を再実行せずに、生成された HTTP レスポンスを配信できます。明示的に有効にする必要があり、Cache-Control ヘッダーを返すだけでは有効になりません。
この例では出力形式を WebP に固定し、三つの画像パスだけを公開します。ソースは、四つのカラーパネルからなる 1,280 × 640 の合成 PNG です。これにより、例が自己完結し、確認しやすくなりますが、写真の画質やファイルサイズの削減を示すものではありません。アップロード、非公開画像、任意のソース URL は扱いません。
プロジェクトの準備
以下のコマンドでは Linux 上の Bash を使用します。動作確認済みのバージョンは、Node.js 26.12.1、Corepack、Yarn 4.12.0、Wrangler 4.154.0 です。Node 26 は保守対象のリリース系列です。これらは再現性のためのバージョン固定であり、他のパッチバージョンに互換性がないという意味ではありません。Node 26 では Corepack を別途用意する必要があります。corepack が利用できない場合は、そのインストール手順に従ってください。また、デプロイ後のキャッシュ確認には cURL と、WebP 対応のブラウザーが必要です。
デプロイには、Workers と Images binding を利用できる Cloudflare アカウント、既存の
workers.dev サブドメイン、そのアカウントに対する Wrangler 認証を用意してください。以下のローカル開発には、クラウドへのデプロイは不要です。デプロイ前に Cloudflare の認証オプションを確認してください。画像変換と Worker リクエストには料金が発生する場合があります。
書き込み可能なディレクトリで、次のブロックを貼り付けてください。既存の image-pipeline ディレクトリの置き換えは拒否され、シェルの作業ディレクトリは元のまま維持されます。
(
for tool in node corepack; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'Missing prerequisite: %s\n' "$tool" >&2
exit 1
}
done
mkdir image-pipeline &&
cd image-pipeline &&
mkdir src &&
cat > package.json <<'JSON' &&
{
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": {
"start": "wrangler dev --ip 127.0.0.1 --port 8787",
"build": "wrangler deploy --dry-run --outdir dist",
"deploy": "wrangler deploy"
},
"devDependencies": { "wrangler": "4.154.0" }
}
JSON
printf 'nodeLinker: node-modules\nignorePath: true\nenableScripts: true\nnpmMinimalAgeGate: 0\n' > .yarnrc.yml &&
touch yarn.lock
)
ローカルのロックファイルにより、この例は独立した Yarn プロジェクトとして扱われます。Yarn 設定では node_modules を選択し、親ディレクトリの yarnPath を継承せず、固定した Yarn 実行ファイルを使います。また、ネイティブ依存関係のインストールスクリプトの実行も許可します。npmMinimalAgeGate: 0 により、この独立した例では、親ディレクトリで設定されたパッケージ公開後の待機期間を適用せずに、固定したリリースをインストールします。既存のアプリケーションに組み込む場合は、組織のポリシーを維持してください。同じ親ディレクトリから、インストールして実際の CLI を確認します。
(cd image-pipeline && corepack yarn install && corepack yarn exec wrangler --version)
4.154.0 が表示されるはずです。インストールに失敗した場合は、報告された原因を修正し、同じ親ディレクトリでこのインストールブロックを再実行してください。package.json とプロジェクトディレクトリは残してください。作成ブロックを再実行しても、既存のディレクトリがあるため、意図どおり拒否されます。作成自体が途中で止まった場合は、続行する前にそのディレクトリを確認するか、新しい空の場所を選んでください。
画像最適化の設定
次の内容を image-pipeline/wrangler.jsonc として保存してください。デプロイ時には、既存のアプリケーションを置き換えないように、自分が所有し、まだ使用していない Worker 名を選んでください。
{
"name": "image-pipeline-example",
"main": "src/index.ts",
"workers_dev": true,
"compatibility_date": "2026-10-28",
"images": { "binding": "IMAGES" },
"cache": { "enabled": true, "cross_version_cache": false }
}
images エントリーが env.IMAGES を提供します。別の cache エントリーで、この Worker の
Workers Cache の利用を明示的に有効にします。以下の画像レスポンスは公開され、3,600 秒間キャッシュできます。HTML と失敗時のレスポンスには no-store を使います。
Worker 全体を image-pipeline/src/index.ts として保存してください。
interface ImagesBinding {
input(stream: ReadableStream<Uint8Array>): {
transform(options: { width: number }): {
output(options: { format: 'image/webp' }): Promise<{
response(options?: { headers?: Record<string, string> }): Response
}>
}
}
}
const sourceBase64 =
'iVBORw0KGgoAAAANSUhEUgAABQAAAAKAAgMAAAC+nT0yAAAADFBMVEXIPCgoyGQoPMjctCj/cAxvAAADMUlEQVR42u3TQQ0AIAADsQWPmMQkiOAzQk9CsyXlzfJGdBVAgAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAnymVd4uzwJdGCBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIEKAAAgQIUAABAgQogAABAhRAgAA/6QB65UPMTK7o+gAAAABJRU5ErkJggg=='
const source = Uint8Array.from(atob(sourceBase64), (value) => value.charCodeAt(0))
const page = `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width">
<title>Responsive image pipeline</title>
<style>body{margin:0}img{display:block;width:100%;max-width:640px;height:auto}</style>
</head>
<body>
<h1>Responsive image pipeline</h1>
<img src="/image/1280.webp"
srcset="/image/320.webp 320w, /image/640.webp 640w, /image/1280.webp 1280w"
sizes="(max-width: 640px) 100vw, 640px" width="1280" height="640"
alt="Four colored panels used to check image resizing">
</body>
</html>`
const widths: Record<string, number> = {
'/image/320.webp': 320,
'/image/640.webp': 640,
'/image/1280.webp': 1280,
}
export default {
async fetch(request: Request, env: { IMAGES: ImagesBinding }): Promise<Response> {
const url = new URL(request.url)
const notFound = () =>
new Response('Not found', { status: 404, headers: { 'Cache-Control': 'no-store' } })
if (request.method !== 'GET' || url.search !== '') return notFound()
if (url.pathname === '/') {
return new Response(page, {
headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' },
})
}
if (!Object.hasOwn(widths, url.pathname)) return notFound()
const width = widths[url.pathname]
try {
return (
await env.IMAGES.input(new Blob([source]).stream())
.transform({ width })
.output({ format: 'image/webp' })
).response({
headers: {
'Cache-Control': 'public, max-age=3600',
'X-Image-Run': crypto.randomUUID(),
},
})
} catch {
return new Response('Image transformation unavailable', {
status: 503,
headers: { 'Cache-Control': 'no-store' },
})
}
},
}
変換を選択するのは /image/320.webp、/image/640.webp、/image/1280.webp だけです。デコード後の寸法はそれぞれ 320 × 160、640 × 320、1,280 × 640 となり、上段に赤と緑、下段に青と黄のパネルが表示されるはずです。バインディングは、要求された出力形式に基づいてレスポンスのコンテンツタイプを設定します。PNG バイト列の名前を変更したり、WebP ヘッダーを設定したりするだけでは、画像は変換されません。
レスポンシブ画像の実装
親ディレクトリからローカルサーバーを起動します。
(cd image-pipeline && corepack yarn start)
http://127.0.0.1:8787/ を開いてください。四つのパネルがビューポートに合わせて、最大表示幅 640 ピクセルで表示されるはずです。各画像パスを直接開き、内容と寸法を確認してください。次の手順に進む前に、Ctrl+C でフォアグラウンドのサーバーを停止してください。ポート 8787 が使用中の場合は、この例を起動する前に、他のリスナーを停止するか、start スクリプトで別のポートを選んでください。
HTML の sizes は、この CSS レイアウトに合わせて、640 ピクセルまでは 100vw、それ以降は 640px としています。320w、640w、1280w の各記述子は、表示幅ではなく、実際のリソース幅を表します。width 属性と height 属性で
2:1 のアスペクト比を確保し、src でデフォルト画像を指定します。HTML の画像選択ルールを参照してください。
ブラウザーのネットワークパネルで、選択された画像のリクエストを確認してください。DPR 1 の 320 ピクセルのビューポート、DPR 1 の 800 ピクセルのビューポート、DPR 2 の 640 ピクセルのビューポートでは、それぞれ必要なリソースが異なります。比較には毎回新しいブラウザーコンテキストを使ってください。選択結果は、ブラウザー、デバイスピクセル比、キャッシュ済みリソースに左右される場合があります。マークアップはブラウザーに候補を渡すものであり、すべてのブラウザーに同じ選択を強制するものではありません。
ローカルの Wrangler は、機能が制限されたオフラインの Images 実装を使います。この実装は、この例のリサイズと明示的な形式指定に対応しています。ページと変換は確認できますが、デプロイ済み Cloudflare 環境でのキャッシュヒットを証明するものではありません。Cloudflare のドキュメントに、これらのローカルバインディングの制限が記載されています。
デプロイとキャッシュの観測
まずビルドします。ドライランに成功すると、アップロードせずに、バンドル済み Worker が
image-pipeline/dist/index.js に書き込まれます。ビルドを繰り返すと、この破棄可能な出力ディレクトリが更新されます。
(cd image-pipeline && corepack yarn build)
アカウント、認証、未使用の Worker 名を確認してから、同じ親ディレクトリでデプロイします。
(cd image-pipeline && corepack yarn deploy)
Wrangler が出力した workers.dev URL を開き、ページと三つの画像 URL を再度確認してください。以下の両方のコマンドで、そのオリジンに置き換えてください。これらは完全な GET リクエストを行い、本文を破棄してヘッダーを出力します。cURL はブラウザーの画像キャッシュを使用しません。
(
command -v curl >/dev/null 2>&1 || { printf 'Install cURL first\n' >&2; exit 1; }
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp' &&
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp'
)
繰り返しリクエストした際に CF-Cache-Status: HIT があるかを確認し、X-Image-Run を直前のレスポンスと比較してください。ヒット時には、Worker がそのレスポンスを生成した際のマーカーが維持されるはずです。Cache-Control ヘッダー、同一の画像バイト列、または変化しないマーカーだけでは、ヒットの証明にはなりません。ステータスがない場合は、デプロイ済みの cache.enabled 設定を確認してください。ミスが続く場合は、レスポンスポリシーとキャッシュキーの確認が必要です。Cloudflare のキャッシュのデバッグガイドに、これらのステータスの説明があります。ローカルプレビューを同等の証拠として扱わないでください。
ここで確認できるのはキャッシュの観測結果であり、速度や帯域幅のベンチマークではありません。パフォーマンスの改善を主張する前に、代表的な画像で実際のバイト数とページの指標を測定してください。
公開サンプルの範囲の維持
ここで扱う画像はすべて公開されており、Worker が受け付けるパスは固定されています。試行する際も、この範囲を維持してください。任意の URL を受け付けると、ソースの取得とアクセス制御という別の問題が加わります。この公開キャッシュ可能なレスポンス経路に、機密画像を代入しないでください。非公開の配信には、専用の認可とキャッシュの設計が必要です。
実際の画像ライブラリでは、オリジナルの保存方法と認可方法を決めてから、合成ソースを置き換えてください。その後、srcset に幅を指定する前に、デコード後の出力幅を検証してください。マネージドの処理と配信も選択肢の一つです。Transloadit の Smart CDN を参照してください。
