Image (レガシー)

Next.js 13から、next/imageコンポーネントはパフォーマンスと開発者体験を向上させるために書き直されました。後方互換性のあるアップグレードソリューションを提供するため、旧next/imageはnext/legacy/imageに名前が変更されました。

新しい next/image APIリファレンスを参照してください

比較

next/legacy/imageと比較して、新しいnext/imageコンポーネントには以下の変更点があります:

• <img>を囲む<span>ラッパーを削除し、ネイティブの計算アスペクト比を採用
• 標準的なstyleプロパティのサポートを追加
  • layoutプロパティを削除し、styleまたはclassNameを使用
  • objectFitプロパティを削除し、styleまたはclassNameを使用
  • objectPositionプロパティを削除し、styleまたはclassNameを使用
• IntersectionObserverの実装を削除し、ネイティブの遅延読み込みを採用
  • ネイティブ対応がないためlazyBoundaryプロパティを削除
  • ネイティブ対応がないためlazyRootプロパティを削除
• loader設定を削除し、loaderプロパティを使用
• altプロパティをオプションから必須に変更
• onLoadingCompleteコールバックが<img>要素への参照を受け取るように変更

必須プロパティ

<Image />コンポーネントには以下のプロパティが必要です。

src

以下のいずれかである必要があります:

• 静的にインポートされた画像ファイル
• 文字列パス。loaderプロパティまたはloader設定に応じて、絶対外部URLまたは内部パス

デフォルトのloaderを使用する場合、ソース画像について以下の点も考慮してください:

• srcが外部URLの場合、remotePatternsの設定も必要
• srcがアニメーション画像または既知の形式(JPEG、PNG、WebP、AVIF、GIF、TIFF)でない場合、画像はそのまま提供される
• srcがSVG形式の場合、unoptimizedまたはdangerouslyAllowSVGが有効でない限りブロックされる

width

widthプロパティは、layoutとsizesプロパティに応じて、_レンダリング_幅または_オリジナル_幅をピクセル単位で表します。

layout="intrinsic"またはlayout="fixed"を使用する場合、widthプロパティは_レンダリング_幅をピクセル単位で表すため、画像の表示サイズに影響します。

layout="responsive"、layout="fill"を使用する場合、widthプロパティは_オリジナル_幅をピクセル単位で表すため、アスペクト比のみに影響します。

widthプロパティは、静的にインポートされた画像またはlayout="fill"の場合を除き必須です。

height

heightプロパティは、layoutとsizesプロパティに応じて、_レンダリング_高さまたは_オリジナル_高さをピクセル単位で表します。

layout="intrinsic"またはlayout="fixed"を使用する場合、heightプロパティは_レンダリング_高さをピクセル単位で表すため、画像の表示サイズに影響します。

layout="responsive"、layout="fill"を使用する場合、heightプロパティは_オリジナル_高さをピクセル単位で表すため、アスペクト比のみに影響します。

heightプロパティは、静的にインポートされた画像またはlayout="fill"の場合を除き必須です。

オプションプロパティ

<Image />コンポーネントは、必須プロパティに加えて多くの追加プロパティを受け入れます。このセクションでは、Imageコンポーネントで最もよく使用されるプロパティについて説明します。より高度なプロパティの詳細については、高度なプロパティセクションを参照してください。

layout

ビューポートのサイズが変化したときの画像のレイアウト動作。

• intrinsicレイアウトのデモ（デフォルト）
  • intrinsicの場合、画像は小さいビューポートでは縮小されますが、大きいビューポートでは元の寸法を維持します。
• fixedレイアウトのデモ
  • fixedの場合、画像の寸法はビューポートの変化に応じて変化しません（レスポンシブなし）。ネイティブのimg要素と同様です。
• responsiveレイアウトのデモ
  • responsiveの場合、画像は小さいビューポートでは縮小され、大きいビューポートでは拡大されます。
  • 親要素のスタイルシートでdisplay: blockを使用していることを確認してください。
• fillレイアウトのデモ
  • fillの場合、親要素が相対位置の場合、画像は幅と高さの両方を親要素の寸法に合わせて伸縮します。
  • これは通常、objectFitプロパティと組み合わせて使用されます。
  • 親要素のスタイルシートでposition: relativeを使用していることを確認してください。
• 背景画像のデモ

loader

URLを解決するためのカスタム関数。Imageコンポーネントのプロパティとしてloaderを設定すると、next.config.jsのimagesセクションで定義されたデフォルトのloaderが上書きされます。

loaderは、以下のパラメータを指定して画像のURL文字列を返す関数です:

• src
• width
• quality

カスタムloaderの使用例:

import Image from 'next/legacy/image'

const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

画像が異なるブレークポイントでどの程度の幅になるかについての情報を提供する文字列。sizesの値は、layout="responsive"またはlayout="fill"を使用する画像のパフォーマンスに大きく影響します。layout="intrinsic"またはlayout="fixed"を使用する画像では無視されます。

sizesプロパティは、画像パフォーマンスに関連する2つの重要な目的を果たします:

第一に、sizesの値は、next/legacy/imageが自動生成するソースセットからどのサイズの画像をダウンロードするかをブラウザが決定するために使用されます。ブラウザが選択する時点では、ページ上の画像のサイズがわからないため、ビューポートと同じサイズまたはそれ以上の画像を選択します。sizesプロパティを使用すると、画像が実際にはフルスクリーンよりも小さいことをブラウザに伝えることができます。sizes値を指定しない場合、デフォルト値の100vw（フルスクリーン幅）が使用されます。

第二に、sizes値は解析され、自動生成されたソースセットの値をトリミングするために使用されます。sizesプロパティに50vwなどのビューポート幅の割合が含まれている場合、ソースセットは不要な小さな値を含まないようにトリミングされます。

例えば、モバイルデバイスではフル幅、タブレットでは2列レイアウト、デスクトップでは3列レイアウトになることがわかっている場合、次のようなsizesプロパティを含める必要があります:

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

このsizesの例は、パフォーマンス指標に劇的な影響を与える可能性があります。33vwのsizesがない場合、サーバーから選択される画像は必要な幅の3倍になります。ファイルサイズは幅の2乗に比例するため、sizesがないとユーザーは必要なサイズの9倍の画像をダウンロードすることになります。

srcsetとsizesについてさらに学ぶ:

• web.dev
• mdn

quality

最適化された画像の品質で、1から100の整数で指定します。100が最高品質です。デフォルトは75です。

priority

trueの場合、画像は高優先度と見なされ、プリロードされます。priorityを使用する画像では、遅延読み込みが自動的に無効になります。

Largest Contentful Paint (LCP)要素として検出された画像にはpriorityプロパティを使用する必要があります。ビューポートサイズによって異なる画像がLCP要素になる可能性があるため、複数の優先度画像を持つことが適切な場合があります。

画面内に表示される画像にのみ使用してください。デフォルトはfalseです。

placeholder

画像の読み込み中に使用するプレースホルダー。可能な値はblurまたはemptyです。デフォルトはemptyです。

blurの場合、blurDataURLプロパティがプレースホルダーとして使用されます。srcが静的インポートからのオブジェクトで、インポートされた画像が.jpg、.png、.webp、または.avifの場合、blurDataURLは自動的に設定されます。

動的画像の場合は、blurDataURLプロパティを指定する必要があります。Plaiceholderなどのソリューションがbase64生成に役立ちます。

emptyの場合、画像の読み込み中にプレースホルダーは表示されず、空白のままになります。

デモを試す:

• blurプレースホルダーのデモ
• blurDataURLプロパティを使用したシマー効果のデモ
• blurDataURLプロパティを使用したカラー効果のデモ

高度なプロパティ

場合によっては、より高度な使用方法が必要になることがあります。<Image />コンポーネントは、以下の高度なプロパティをオプションで受け入れます。

style

基になる画像要素にCSSスタイルを渡すことができます。

すべてのlayoutモードは画像要素に独自のスタイルを適用し、これらの自動スタイルはstyleプロパティよりも優先されることに注意してください。

また、必須のwidthとheightプロパティがスタイルと相互作用する可能性があることにも注意してください。スタイルを使用して画像のwidthを変更する場合は、height="auto"スタイルも設定する必要があります。そうしないと画像が歪んで表示されます。

objectFit

layout="fill"を使用する場合、画像が親コンテナにどのようにフィットするかを定義します。

この値は、src画像のobject-fit CSSプロパティに渡されます。

objectPosition

layout="fill"を使用する場合、画像が親要素内でどのように配置されるかを定義します。

この値は、画像に適用されるobject-position CSSプロパティに渡されます。

onLoadingComplete

画像が完全に読み込まれ、プレースホルダーが削除された後に呼び出されるコールバック関数。

onLoadingComplete関数は、以下のプロパティを持つオブジェクトを1つのパラメータとして受け取ります:

• naturalWidth
• naturalHeight

loading

画像の読み込み動作。デフォルトはlazyです。

lazyの場合、ビューポートから計算された距離に達するまで画像の読み込みを遅延させます。

eagerの場合、画像をすぐに読み込みます。

詳細を学ぶ

blurDataURL

src画像が正常に読み込まれる前にプレースホルダーとして使用されるData URL。placeholder="blur"と組み合わせた場合にのみ有効です。

base64エンコードされた画像である必要があります。拡大されてぼかされるため、非常に小さい画像（10px以下）が推奨されます。プレースホルダーとして大きな画像を含めると、アプリケーションのパフォーマンスが低下する可能性があります。

デモを試す:

• デフォルトのblurDataURLプロパティのデモ
• blurDataURLプロパティを使用したシマー効果のデモ
• blurDataURLプロパティを使用したカラー効果のデモ

画像に合わせて単色のData URLを生成することもできます。

lazyBoundary

ビューポートと画像の交差を検出し、遅延読み込みをトリガーするために使用される境界ボックスとして機能する文字列（marginプロパティと同様の構文）。デフォルトは"200px"です。

画像がルートドキュメント以外のスクロール可能な親要素内にある場合は、lazyRootプロパティも割り当てる必要があります。

詳細を学ぶ

lazyRoot

スクロール可能な親要素を指すReactのRef。デフォルトはnull（ドキュメントビューポート）です。

Refは、DOM要素または基礎となるDOM要素にRefを転送するReactコンポーネントを指している必要があります。

DOM要素を指す例

import Image from 'next/legacy/image'
import React from 'react'

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

Reactコンポーネントを指す例

import Image from 'next/legacy/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

詳細を学ぶ

unoptimized

trueに設定すると、srcのソース画像は品質、サイズ、フォーマットを変更せずにそのまま提供されます。デフォルトはfalseです。

これは、最適化の恩恵を受けない画像（1KB未満の小さな画像、ベクター画像（SVG）、アニメーション画像（GIF）など）に有用です。

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Next.js 12.3.0以降では、以下の設定でnext.config.jsを更新することで、すべての画像にこのプロパティを適用できます:

module.exports = {
  images: {
    unoptimized: true,
  },
}

その他のプロパティ

<Image />コンポーネントの他のプロパティは、以下の例外を除いて、基盤となるimg要素に渡されます:

• srcSet。代わりにデバイスサイズを使用してください。
• ref。代わりにonLoadingCompleteを使用してください。
• decoding。常に"async"です。

設定オプション

リモートパターン

悪意のあるユーザーからアプリケーションを保護するため、外部画像を使用するには設定が必要です。これにより、Next.jsの画像最適化APIから提供される外部画像があなたのアカウントからのみであることが保証されます。これらの外部画像は、以下のようにnext.config.jsファイルのremotePatternsプロパティで設定できます:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
        search: '',
      },
    ],
  },
}

知っておくと良い: 上記の例では、next/legacy/imageのsrcプロパティがhttps://example.com/account123/で始まり、クエリ文字列を持たないことが保証されます。他のプロトコル、ホスト名、ポート、または一致しないパスは400 Bad Requestで応答します。

以下は、hostnameにワイルドカードパターンを使用したnext.config.jsファイルのremotePatternsプロパティの例です:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
        port: '',
        search: '',
      },
    ],
  },
}

知っておくと良い: 上記の例では、next/legacy/imageのsrcプロパティがhttps://img1.example.comまたはhttps://me.avatar.example.com、または任意の数のサブドメインで始まることが保証されます。ポートやクエリ文字列を持つことはできません。他のプロトコルや一致しないホスト名は400 Bad Requestで応答します。

ワイルドカードパターンはpathnameとhostnameの両方で使用でき、以下の構文を持ちます:

• * 単一のパスセグメントまたはサブドメインに一致
• ** 末尾の任意の数のパスセグメントまたは先頭のサブドメインに一致

**構文はパターンの途中では機能しません。

知っておくと良い: protocol、port、pathname、またはsearchを省略すると、ワイルドカード**が暗黙的に適用されます。これは、意図しないURLを最適化する可能性があるため推奨されません。

以下は、searchを使用したnext.config.jsファイルのremotePatternsプロパティの例です:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

知っておくと良い: 上記の例では、next/legacy/imageのsrcプロパティがhttps://assets.example.comで始まり、正確なクエリ文字列?v=1727111025337を持つことが保証されます。他のプロトコルやクエリ文字列は400 Bad Requestで応答します。

ドメイン

警告: アプリケーションを悪意のあるユーザーから保護するため、Next.js 14以降では厳格なremotePatternsが推奨されます。ドメインから提供されるすべてのコンテンツを所有している場合にのみdomainsを使用してください。

remotePatternsと同様に、domains設定を使用して外部画像の許可されたホスト名のリストを提供できます。

ただし、domains設定はワイルドカードパターンマッチングをサポートせず、プロトコル、ポート、またはパス名を制限できません。

以下は、next.config.jsファイルのdomainsプロパティの例です:

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

ローダー設定

Next.js組み込みの画像最適化APIの代わりにクラウドプロバイダーを使用して画像を最適化したい場合、next.config.jsファイルでloaderとpathプレフィックスを設定できます。これにより、Imageのsrcに相対URLを使用し、プロバイダー向けの正しい絶対URLを自動生成できます。

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

組み込みローダー

以下の画像最適化クラウドプロバイダーが含まれています:

• デフォルト: next dev、next start、またはカスタムサーバーで自動的に動作
• Vercel: Vercelにデプロイすると自動的に動作、設定不要。詳細
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• カスタム: loader: 'custom' next/legacy/imageコンポーネントのloaderプロパティを実装してカスタムクラウドプロバイダーを使用

他のプロバイダーが必要な場合は、next/legacy/imageでloaderプロパティを使用できます。

output: 'export'を使用すると、ビルド時に画像を最適化できません（オンデマンドのみ）。output: 'export'でnext/legacy/imageを使用するには、デフォルト以外のローダーを使用する必要があります。ディスカッションを参照

高度な設定

以下の設定は高度な使用例向けで、通常は必要ありません。以下のプロパティを設定すると、将来の更新でNext.jsのデフォルトを上書きします。

デバイスサイズ

ユーザーの予想されるデバイス幅がわかっている場合、next.config.jsのdeviceSizesプロパティを使用してデバイス幅ブレークポイントのリストを指定できます。これらの幅は、next/legacy/imageコンポーネントがlayout="responsive"またはlayout="fill"を使用する際に、ユーザーのデバイスに適切な画像が提供されるようにするために使用されます。

設定が提供されない場合、以下のデフォルトが使用されます。

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

画像サイズ

next.config.jsファイルのimages.imageSizesプロパティを使用して、画像幅のリストを指定できます。これらの幅はデバイスサイズの配列と連結され、画像srcsetを生成するための完全なサイズ配列を形成します。

2つの別々のリストがある理由は、imageSizesはsizesプロパティを提供する画像（画面の全幅より小さいことを示す）にのみ使用されるためです。したがって、imageSizesのサイズはすべてdeviceSizesの最小サイズより小さくする必要があります。

設定が提供されない場合、以下のデフォルトが使用されます。

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

許容フォーマット

デフォルトの画像最適化APIは、リクエストのAcceptヘッダーを介してブラウザがサポートする画像フォーマットを自動的に検出し、最適な出力フォーマットを決定します。

Acceptヘッダーが設定されたフォーマットの複数と一致する場合、配列の最初の一致が使用されます。したがって、配列の順序が重要です。一致がない場合（またはソース画像がアニメーションの場合）、画像最適化APIは元の画像のフォーマットにフォールバックします。

設定が提供されない場合、以下のデフォルトが使用されます。

module.exports = {
  images: {
    formats: ['image/webp'],
  },
}

AVIFサポートを有効にすることもでき、ブラウザがAVIFをサポートしていない場合、src画像の元のフォーマットにフォールバックします:

module.exports = {
  images: {
    formats: ['image/avif'],
  },
}

知っておくと良い:

• ほとんどのユースケースではWebPを使用することを推奨します。
• AVIFは一般的にエンコードに50%長くかかりますが、WebPと比べて20%小さく圧縮されます。つまり、画像が最初にリクエストされるときは通常遅くなりますが、キャッシュされた後続のリクエストは速くなります。
• Next.jsの前にProxy/CDNを自己ホストしている場合、Acceptヘッダーを転送するようにProxyを設定する必要があります。

キャッシュ動作

以下は、デフォルトローダーのキャッシュアルゴリズムについて説明しています。他のすべてのローダーについては、クラウドプロバイダーのドキュメントを参照してください。

画像はリクエスト時に動的に最適化され、<distDir>/cache/imagesディレクトリに保存されます。最適化された画像ファイルは、有効期限に達するまで後続のリクエストに対して提供されます。キャッシュされているが期限切れのファイルに一致するリクエストが行われた場合、期限切れの画像がすぐに提供されます（stale）。その後、バックグラウンドで画像が再最適化され（再検証）、新しい有効期限でキャッシュに保存されます。

画像のキャッシュステータスは、x-nextjs-cache（Vercelにデプロイ時はx-vercel-cache）レスポンスヘッダーの値を読み取ることで確認できます。可能な値は以下の通りです:

• MISS - パスがキャッシュにない（最初の訪問時に最大1回発生）
• STALE - パスはキャッシュにあるが再検証時間を超えているため、バックグラウンドで更新される
• HIT - パスはキャッシュにあり、再検証時間を超えていない

有効期限（またはMax Age）は、minimumCacheTTL設定または上流画像のCache-Controlヘッダーのいずれか大きい方で定義されます。具体的には、Cache-Controlヘッダーのmax-age値が使用されます。s-maxageとmax-ageの両方が見つかった場合、s-maxageが優先されます。max-ageはCDNやブラウザを含む下流のクライアントにも渡されます。

• 上流画像にCache-Controlヘッダーがないか、値が非常に低い場合、minimumCacheTTLを設定してキャッシュ期間を延長できます。
• 生成される可能性のある画像の総数を減らすために、deviceSizesとimageSizesを設定できます。
• 複数のフォーマットを無効にして単一の画像フォーマットを優先するためにフォーマットを設定できます。

最小キャッシュTTL

キャッシュされた最適化画像のTime to Live（TTL）を秒単位で設定できます。多くの場合、静的画像インポートを使用する方が良いでしょう。これは自動的にファイル内容をハッシュし、Cache-Controlヘッダーをimmutableとして永遠にキャッシュします。

設定が提供されない場合、以下のデフォルトが使用されます。

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1分
  },
}

TTLを増やして再検証の回数を減らし、コストを削減できます:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31日
  },
}

最適化画像の有効期限（またはMax Age）は、minimumCacheTTLまたは上流画像のCache-Controlヘッダーのいずれか大きい方で定義されます。

画像ごとにキャッシュ動作を変更する必要がある場合、headersを設定して上流画像（例: /_next/image自体ではなく/some-asset.jpg）にCache-Controlヘッダーを設定できます。

現時点でキャッシュを無効化するメカニズムはないため、minimumCacheTTLを低く保つことが最善です。そうでない場合、srcプロパティを手動で変更するか、<distDir>/cache/imagesを削除する必要があるかもしれません。

静的インポートの無効化

デフォルトの動作では、import icon from './icon.png'などの静的ファイルをインポートし、それをsrcプロパティに渡すことができます。

場合によっては、インポートの動作が異なることを期待する他のプラグインと競合するため、この機能を無効にしたいことがあります。

next.config.js内で静的画像インポートを無効にできます:

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

SVGの危険な許可

デフォルトのローダーは、いくつかの理由でSVG画像を最適化しません。第一に、SVGはベクターフォーマットであるため、ロスレスでサイズ変更できます。第二に、SVGにはHTML/CSSと同じ機能が多く含まれており、適切なContent Security Policy (CSP) ヘッダーがないと脆弱性につながる可能性があります。

したがって、srcプロパティがSVGであることがわかっている場合は、unoptimizedプロパティを使用することを推奨します。これはsrcが".svg"で終わる場合に自動的に行われます。

ただし、デフォルトの画像最適化APIでSVG画像を提供する必要がある場合、next.config.js内でdangerouslyAllowSVGを設定できます:

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

さらに、画像に埋め込まれたスクリプトの実行を防ぐために、contentDispositionTypeを設定してブラウザに画像をダウンロードさせ、contentSecurityPolicyを設定することを強く推奨します。

contentDispositionType

デフォルトのローダーは、APIが任意のリモート画像を提供できるため、追加の保護としてContent-Dispositionヘッダーをattachmentに設定します。

デフォルト値はattachmentで、直接訪問時にブラウザに画像をダウンロードさせます。これはdangerouslyAllowSVGがtrueの場合に特に重要です。

オプションでinlineを設定し、直接訪問時にブラウザが画像をダウンロードせずにレンダリングできるようにできます。

module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

アニメーション画像

デフォルトのローダーは、アニメーション画像の画像最適化を自動的にバイパスし、画像をそのまま提供します。

アニメーションファイルの自動検出はベストエフォートで、GIF、APNG、WebPをサポートします。特定のアニメーション画像に対して画像最適化を明示的にバイパスしたい場合は、unoptimizedプロパティを使用してください。

バージョン履歴