netlify-image-cdn

Netlify Image CDN

url クエリパラメーターを指定してエンドポイントにリクエストすると、画像を変換できます。現在ドキュメント化されている方法はこれだけです。レガシー形式はありません。

GET /.netlify/images?url=<source>[&w=][&h=][&fit=][&position=][&fm=][&q=]

# resize a deployed image to 50px wide
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&w=50'

url は必須で、それ以外のパラメーターはすべて省略可能です。

クエリパラメーター

パラメーター	目的	値	デフォルト
url	ソースアセット（必須）	相対パスまたはリモート URL	—
w	幅（ピクセル）	整数	—
h	高さ（ピクセル）	整数	—
fit	リサイズ動作	contain、cover、fill	contain
position	fit=cover の場合のトリミング位置	top、bottom、left、right、center	center
fm	出力形式	avif、jpg、png、webp、gif、blurhash	コンテンツネゴシエーション
q	非可逆圧縮の品質	整数 1～100	75

よく使う変換

# resize + crop to a 50px square, retaining the left side
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50&position=left'

# convert JPEG to PNG (response carries content-type: image/png)
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=png'

# convert JPEG to AVIF at medium quality
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=avif&q=50'

fit の動作

• contain（デフォルト）： アスペクト比を維持します。指定したサイズより小さくなる寸法が生じる場合があります。片方の寸法を指定すると、もう片方は自動計算されます。
• cover： 余分な部分をトリミングして、指定したサイズにぴったり合わせます。w と h の両方が必須です。どちらかを省略すると無効になります。残す部分は position で指定します。
• fill： アスペクト比が異なる場合は引き伸ばしたり、押し縮めたりして、指定したサイズにぴったり合わせます。

形式に関する注意事項

• q が適用されるのは、出力形式が avif、jpg、gif、webp の場合のみです。
• webp と gif は静止画とアニメーションの両方に対応します。
• fm を省略すると、Accept ヘッダーに基づいて形式がコンテンツネゴシエーションされます。webp が許可されていれば webp、それ以外で avif が許可されていれば avif、どちらも許可されていなければ元の形式になります。ソースのみを指定したリクエスト（ほかのパラメーターなし）でも webp／avif に変換されますが、サイズと形状は維持されます。

リモートソース画像

リモートソースは、変換前に netlify.toml で許可リストに登録する必要があります。登録されていない場合、リクエストは失敗します。

[images]
  remote_images = ['https://my-images\.com/.*', 'https://animals.more-images.com/[bcr]at/.*']

リモートソース URL は url パラメーターに指定する前に、encodeURIComponent でパーセントエンコードしてください。? や & を含む URL は、エンコードしないと正しく処理されません。

const src = `/.netlify/images?url=${encodeURIComponent('https://my-images.com/owl.jpeg?v=2')}&w=400`;

制約：

• リモートソースは誰でもアクセスできる必要があります。
• リモートソースの取得時に、認証情報を含むヘッダー（Authorization、Cookie）は転送されません。認証が必要なソースには、URL 自体に認証情報を含める（S3 の署名付き URL など）ものを使用し、remote_images パターンが完全な URL と一致するようにしてください。

remote_images の正規表現でのエスケープ

意味のあるエスケープは、ドットをリテラルとして扱うための \. だけです。スラッシュはメタ文字ではありません。https:\/\/ のようには書かないでください。netlify.toml では、シングルクォートのリテラル文字列（'https://example\.com/.*'）を使うか、ダブルクォート文字列ではバックスラッシュを二重にしてください（"https://example\\.com/.*"）。ダブルクォート内で \. をそのまま使うと、無効な TOML になります。

レスポンスコード

• 無効な変換パラメーター値 → 404。
• 新しい有効な変換 → コンテンツと一致する content-type を含む 200。
• 変換済み（キャッシュ済み）の画像 → 304。

複数の画像でパラメーターを再利用する

リダイレクト／リライトを使って、わかりやすいパスをエンドポイントにマッピングします。

_redirects：

/transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200

netlify.toml：

[[redirects]]
  from = "/transform-small/*"
  to = "/.netlify/images?url=/:splat&w=50&h=50"
  status = 200

この設定により、GET /transform-small/owl.jpeg は変換済み画像を返します。変換のためのサイト間リダイレクトは推奨されません。サイトのパフォーマンスが低下する可能性があります。

キャッシュヘッダー

サイト独自ドメイン上のソース画像にカスタムヘッダーを適用すると、変換後の出力にも引き継がれます。

netlify.toml：

[[headers]]
  for = "/source-images/*"
  [headers.values]
    Cache-Control = "public, max-age=604800, must-revalidate"

• カスタムヘッダーを適用できるのは、サイトのドメイン上にあるソース画像のみです。リモートソース画像には適用できません（Netlify は外部ドメインから送信されたキャッシュヘッダーを尊重します）。
• ソース画像の Cache-Control が適用されるのはブラウザーと Netlify の手前にある CDN のみで、Netlify Cache には適用されません。

ぼかしプレースホルダー（fm=blurhash）

fm=blurhash は画像データではなく、BlurHash のテキスト文字列を返します。<img src>（または CSS の背景）に指定しても何も表示されません。あらかじめ文字列を取得し、BlurHash ライブラリ（https://blurha.sh）を使ってクライアント側でデコードしてください。そのうえで、`fm=blurhash` を指定せずに別のリクエストで実際の画像を読み込みます。

ローカル開発

/.netlify/images エンドポイント、[images] の許可リスト設定、画像リダイレクトは、netlify dev（Netlify CLI）の実行時にのみ機能します。ローカル環境で /.netlify/images が 404 になる場合、ほとんどの場合、netlify dev ではなくフレームワークの開発サーバー（vite、next dev、astro dev）が起動しています。URL 自体に問題がないことがほとんどです。netlify dev でローカル環境を起動してください。

ユーザーがアップロードした画像のパイプライン

Functions + Blobs + Image CDN を組み合わせるパイプライン（ユーザーがアップロードした画像を処理するもの）については、references/user-uploads.md を参照してください。

フレームワークでの画像処理

多くのフレームワークでは、組み込みの画像最適化が Netlify Image CDN 経由で行われます。フレームワーク標準の画像コンポーネント／構文を使用し、リモート許可リストのみを設定してください。リストにないフレームワークでは、/.netlify/images を直接呼び出してください。

フレームワーク	前提条件	リモート許可リストの場所
Angular	なし。NgOptimizedImage が自動的に使用します	netlify.toml の [images] remote_images
Astro	なし。<Image /> が自動的に使用します	astro.config.mjs の image.domains または image.remotePatterns
Gatsby（5.13 以降および 5.11 以前の両方）	環境変数 NETLIFY_IMAGE_CDN=true を設定し、Contentful／Drupal／WordPress のソースプラグインを使用します	netlify.toml の [images] remote_images
Next.js	Next.js 13.5 以降および Next.js アダプター v5	next.config.js の remotePatterns
Nuxt	なし。nuxt/image モジュールが自動的に使用します	nuxt.config.ts の image.domains

セットアップガイド：Angular、Astro、Gatsby、Next.js、Nuxt。

その他の制約

• デプロイ時の動作：変換はアトミックデプロイに対応しています。新しいデプロイでソース画像を変更すると、それ以降のリクエストで変換が再実行されます。
• スプリットテストには対応していません。画像の結果がスプリットテストの各ブランチで一致しない場合があります。
• Netlify Image CDN は、Netlify の HIPAA 準拠ホスティングサービスには含まれません。

インタラクティブなパラメータプレイグラウンド：https://image-cdn-playground.netlify.app/

Netlify のルール（image-cdn）

これらは組織内の規約であり、ドキュメントに記載された事実ではありません。ctx-gen によってレンダリングされるスキルに統合され、生成されることはありません。スキルのメンテナーが管理しています。

1. ユーザーがアップロードした画像のパイプライン（Functions + Blobs + Image CDN を組み合わせたもの）については、このスキルの references/user-uploads.md を参照してください。特定のドキュメントを単独の情報源としない、執筆済みのガイドです。
2. リモートのソース URL は、url パラメーターに指定する前にパーセントエンコードしてください（encodeURIComponent）。? または & を含む URL は、エンコードしないと動作しません。
3. fm=blurhash が返すのは BlurHash のテキスト文字列であり、画像データではありません。<img src>（または CSS の背景画像）に指定しても何も表示されません。文字列を事前に取得し、BlurHash ライブラリを使ってクライアント側でデコードし、fm=blurhash を指定せずに別のリクエストで実際の画像を読み込んでください。
4. /.netlify/images でローカルの 404 が発生する場合は、ほぼ常に netlify dev ではなく、フレームワークの開発サーバー（vite、next dev、astro dev）が実行されています。エンドポイント、[images] の許可リスト、画像リダイレクトは netlify dev の実行時にのみ存在します。通常、URL 自体に問題はありません。
5. remote_images パターンでは、意味のある正規表現のエスケープ文字はドットです。スラッシュはメタ文字ではないため、https:\/\/ と書かないでください。netlify.toml では、単一引用符で囲んだリテラル文字列（'https://example\.com/.*'）を使うか、二重引用符で囲んだ文字列のバックスラッシュを二重にしてください（"https://example\\.com/.*"）。二重引用符内のエスケープされていない \. は無効な TOML です。