Image

このAPIリファレンスでは、Image コンポーネントで利用可能なPropsと設定オプションの使用方法について説明します。機能と使用方法については、Image コンポーネントのページを参照してください。

import Image from 'next/image'
 
export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

Props

Image コンポーネントで利用可能なPropsの概要を以下に示します

必須Props

Image コンポーネントには、以下のプロパティが必要です: `src`、`alt`、`width` および `height` (または `fill`)。

import Image from 'next/image'
 
export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </div>
  )
}

src

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

• 静的にインポートされた画像ファイル
• パス文字列。これは、`loader` プロパティに応じて、絶対外部URLまたは内部パスのいずれかになります。

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

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

width

`width` プロパティは、画像の*本来の*ピクセル幅を表します。このプロパティは、画像の正しいアスペクト比を推測し、読み込み中のレイアウトシフトを防ぐために使用されます。これは、HTMLの``タグの`width`属性と同様に、CSSによって制御される画像のレンダリングサイズを決定するものではありません。

静的にインポートされた画像、または`fill` プロパティを持つ画像を除き、必須です。

height

`height` プロパティは、画像の*本来の*ピクセル高さを表します。このプロパティは、画像の正しいアスペクト比を推測し、読み込み中のレイアウトシフトを防ぐために使用されます。これは、HTMLの``タグの`height`属性と同様に、CSSによって制御される画像のレンダリングサイズを決定するものではありません。

静的にインポートされた画像、または`fill` プロパティを持つ画像を除き、必須です。

補足

• `width` と `height` プロパティを組み合わせることで、画像の縦横比が決定され、ブラウザは画像を読み込む前にそのためのスペースを確保するためにこれを使用します。
• 本来のサイズが常にブラウザでのレンダリングサイズを意味するわけではありません。レンダリングサイズは親コンテナによって決定されます。たとえば、親コンテナが本来のサイズよりも小さい場合、画像はコンテナに合わせて縮小されます。
• `width` と `height` が不明な場合は、`fill` プロパティを使用できます。

alt

`alt` プロパティは、スクリーンリーダーや検索エンジン向けに画像を説明するために使用されます。また、画像が無効になっている場合や、画像の読み込み中にエラーが発生した場合の代替テキストとしても使用されます。

画像をページの意味を変えることなく置き換えられるテキストを含める必要があります。画像を補足するものではなく、画像の上または下にすでに提供されている情報を繰り返すべきではありません。

画像が純粋な装飾であるか、またはユーザー向けでない場合、`alt` プロパティは空文字列 (`alt=""`) にすべきです。

詳細はこちら

オプションProps

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

loader

画像URLを解決するために使用されるカスタム関数。

`loader` は、以下のパラメータが与えられた場合に、画像のURL文字列を返す関数です

• src
• width
• quality

カスタムローダーの使用例を以下に示します

'use client'
 
import Image from 'next/image'
 
const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
 
export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

補足: `loader` のように関数を受け入れるPropsを使用する場合、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

あるいは、`next.config.js` の `loaderFile` 設定を使用して、`next/image` のすべてのインスタンスをプロパティを渡すことなく設定することもできます。

fill

fill={true} // {true} | {false}

画像が親要素を埋めるようにする真偽値。これは、`width` と `height` が不明な場合に役立ちます。

親要素は、`position: "relative"`、`position: "fixed"`、または `position: "absolute"` スタイルを必ず割り当てる必要があります。

デフォルトでは、`img` 要素には自動的に `position: "absolute"` スタイルが割り当てられます。

画像にスタイルが適用されていない場合、画像はコンテナに合わせて引き伸ばされます。コンテナに合わせてレターボックス化され、アスペクト比を維持する画像には、`object-fit: "contain"` を設定することをお勧めします。

あるいは、`object-fit: "cover"` を設定すると、画像はコンテナ全体を埋め、アスペクト比を維持するために切り抜かれます。

詳細については、以下も参照してください

• position
• object-fit
• object-position

sizes

メディアクエリに似た文字列で、異なるブレークポイントでの画像の幅に関する情報を提供します。`fill`を使用する画像、またはレスポンシブサイズを持つようにスタイル設定された画像の場合、`sizes` の値はパフォーマンスに大きく影響します。

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

• まず、`sizes` の値は、`next/image` が自動生成する `srcset` から、ブラウザがダウンロードする画像のサイズを決定するために使用されます。ブラウザが選択する際、ページ上の画像のサイズはまだ不明であるため、ビューポートと同じかそれよりも大きい画像を選択します。`sizes` プロパティを使用すると、画像が実際には全画面よりも小さいことをブラウザに伝えることができます。`fill` プロパティを持つ画像で `sizes` の値を指定しない場合、デフォルト値の `100vw` (全画面幅) が使用されます。
• 次に、`sizes` プロパティは、自動生成される `srcset` の値の動作を変更します。`sizes` の値がない場合、固定サイズの画像 (1x/2xなど) に適した小さな `srcset` が生成されます。`sizes` が定義されている場合、レスポンシブ画像 (640w/750wなど) に適した大きな `srcset` が生成されます。`sizes` プロパティに `50vw` のようなビューポート幅のパーセンテージを表すサイズが含まれている場合、`srcset` は不要なほど小さい値を含まないようにトリミングされます。

たとえば、スタイリングによって画像がモバイルデバイスで全幅表示され、タブレットで2カラムレイアウト、デスクトップディスプレイで3カラムレイアウトになることがわかっている場合、次のような `sizes` プロパティを含める必要があります

import Image from 'next/image'
 
export default function Page() {
  return (
    <div className="grid-element">
      <Image
        fill
        src="/example.png"
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
      />
    </div>
  )
}

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

`srcset` と `sizes` について詳しくはこちら

• web.dev
• mdn

quality

quality={75} // {number 1-100}

最適化された画像の品質。`1` から `100` までの整数で、`100` が最高の品質であり、したがって最大のファイルサイズになります。デフォルトは `75` です。

`next.config.js` で`qualities`設定が定義されている場合、`quality` プロパティは設定で定義された値のいずれかに一致する必要があります。

補足: 元のソース画像がすでに低品質であった場合、`quality` プロパティを高く設定しすぎると、結果として最適化された画像が元のソース画像よりも大きくなる可能性があります。

priority

priority={false} // {false} | {true}

true の場合、Next.js は画像をプリロードします。`priority` を使用する画像の場合、遅延ロードは自動的に無効になります。`loading` プロパティも使用され、`lazy` に設定されている場合、`priority` プロパティは使用できません。`loading` プロパティは高度なユースケースのみを対象としています。`priority` が必要な場合は `loading` を削除してください。

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

画像がファーストビュー内に表示される場合にのみ使用すべきです。デフォルトは `false` です。

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

画像の読み込み中に使用するプレースホルダー。`blur`、`empty`、または `data:image/...` のいずれかの値が可能です。デフォルトは `empty` です。

`blur` の場合、`blurDataURL` プロパティがプレースホルダーとして使用されます。`src` が静的インポートからのオブジェクトで、インポートされた画像が`.jpg`、`.png`、`.webp`、または`.avif` の場合、画像がアニメーションであると検出された場合を除き、`blurDataURL` は自動的に入力されます。

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

`data:image/...` の場合、画像の読み込み中にデータURLがプレースホルダーとして使用されます。

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

試してみる

• `blur` プレースホルダーのデモ
• データURL `placeholder` プロパティによるシマー効果のデモ
• `blurDataURL` プロパティによるカラー効果のデモ

高度なProps

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

style

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

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}
 
export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

必須の `width` と `height` プロパティは、あなたのスタイリングと相互作用する可能性があることを覚えておいてください。画像の幅を変更するためにスタイリングを使用する場合、本来のアスペクト比を維持するために高さも `auto` に設定する必要があります。そうしないと画像が歪みます。

onLoadingComplete

'use client'
 
<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />

警告: Next.js 14 以降、`onLoad` が優先されるため非推奨です。

画像が完全にロードされ、プレースホルダーが削除されたときに呼び出されるコールバック関数。

コールバック関数は、基礎となる `` 要素への参照である1つの引数とともに呼び出されます。

補足: `onLoadingComplete` のように関数を受け入れるPropsを使用する場合、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

onLoad

<Image onLoad={(e) => console.log(e.target.naturalWidth)} />

画像が完全にロードされ、プレースホルダーが削除されたときに呼び出されるコールバック関数。

コールバック関数は、基礎となる `` 要素を参照する `target` を持つイベントを引数として呼び出されます。

補足: `onLoad` のように関数を受け入れるPropsを使用する場合、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

onError

<Image onError={(e) => console.error(e.target.id)} />

画像の読み込みに失敗した場合に呼び出されるコールバック関数。

補足: `onError` のように関数を受け入れるPropsを使用する場合、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

loading

loading = 'lazy' // {lazy} | {eager}

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

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

`eager` の場合、画像を直ちに読み込みます。

`loading` 属性について詳しくはこちら。

blurDataURL

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

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

試してみる

• デフォルトの`blurDataURL` プロパティのデモ
• `blurDataURL` プロパティによるカラー効果のデモ

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

unoptimized

unoptimized = {false} // {false} | {true}

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,
  },
}

overrideSrc

`` コンポーネントに `src` プロパティを提供すると、結果として生成される `` に対して `srcset` と `src` 属性の両方が自動的に生成されます。

<Image src="/me.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

場合によっては、`src` 属性が生成されることが望ましくないことがあり、`overrideSrc` プロパティを使用してそれを上書きしたい場合があります。

たとえば、既存のウェブサイトを `` から `` にアップグレードする場合、画像ランキングや再クロールの回避といったSEO目的で同じ `src` 属性を維持したい場合があります。

<Image src="/me.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

ブラウザに対し、他のコンテンツ更新を表示する前に画像をデコードするのを待つべきかどうかを示すヒント。デフォルトは `async` です。

可能な値は以下の通りです

• `async` - 画像を非同期的にデコードし、完了する前に他のコンテンツがレンダリングされることを許可します。
• `sync` - 画像を同期的にデコードし、他のコンテンツとアトミックに表示します。
• `auto` - デコードモードに好みなし。ブラウザが最適なものを決定します。

`decoding` 属性について詳しくはこちら。

その他のProps

`` コンポーネントの他のプロパティは、以下の例外を除き、基礎となる `img` 要素に渡されます。

• `srcSet`。代わりにデバイスサイズを使用してください。

設定オプション

Propsに加えて、`next.config.js` でImage コンポーネントを設定できます。以下のオプションが利用可能です。

localPatterns

特定のパスのみを最適化し、他のすべてのパスをブロックするために、`next.config.js` ファイルで `localPatterns` をオプションで設定できます。

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

補足: 上記の例は、`next/image` の `src` プロパティが `/assets/images/` で始まる必要があり、クエリ文字列を含んではならないことを保証します。他のパスを最適化しようとすると、400 Bad Request が返されます。

remotePatterns

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

module.exports = {
  images: {
    remotePatterns: [new URL('https://example.com/account123/**')],
  },
}

Next.js の 15.3.0 より前のバージョンでは、オブジェクトを使用して `remotePatterns` を設定できます。

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

補足: 上記の例は、`next/image` の `src` プロパティが `https://example.com/account123/` で始まる必要があり、クエリ文字列を含んではならないことを保証します。他のプロトコル、ホスト名、ポート、または一致しないパスは、400 Bad Request で応答します。

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

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

補足: 上記の例は、`next/image` の `src` プロパティが `https://img1.example.com` または `https://me.avatar.example.com`、あるいは任意の数のサブドメインで始まる必要があることを保証します。ポートやクエリ文字列を含めることはできません。他のプロトコルや一致しないホスト名は、400 Bad Request で応答します。

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

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

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

補足: `protocol`、`port`、`pathname`、または `search` を省略すると、ワイルドカード `**` が暗黙的に使用されます。これは、悪意のあるアクターが意図しないURLを最適化することを許可する可能性があるため、推奨されません。

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

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

補足: 上記の例は、`next/image` の `src` プロパティが `https://assets.example.com` で始まり、正確なクエリ文字列 `?v=1727111025337` を持つ必要があることを保証します。他のプロトコルやクエリ文字列は、400 Bad Request で応答します。

domains

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

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

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

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

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

loaderFile

Next.js 内蔵のImage Optimization APIを使用する代わりに、クラウドプロバイダを使用して画像を最適化したい場合は、以下のように`next.config.js`で`loaderFile`を設定できます。

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

これはNext.jsアプリケーションのルートからの相対パスのファイルを指す必要があります。このファイルは、文字列を返すデフォルト関数をエクスポートする必要があります。例：

'use client'
 
export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

あるいは、`loader` propを使用して、`next/image` の各インスタンスを設定することもできます。

例

• カスタム画像ローダー設定

補足: 関数を受け入れる画像ローダーファイルをカスタマイズする場合、提供された関数をシリアライズするためにクライアントコンポーネントを使用する必要があります。

詳細設定

以下の設定は高度なユースケース向けであり、通常は必要ありません。以下のプロパティを設定することを選択した場合、将来のアップデートでNext.jsのデフォルトに対する変更が上書きされます。

deviceSizes

ユーザーの想定されるデバイス幅を知っている場合、`next.config.js` の `deviceSizes` プロパティを使用してデバイス幅のブレークポイントのリストを指定できます。これらの幅は、`next/image` コンポーネントが`sizes` プロパティを使用して、ユーザーのデバイスに正しい画像が提供されるようにする際に使用されます。

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

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

imageSizes

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

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

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

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

qualities

デフォルトのImage Optimization APIは、1から100までのすべての品質を自動的に許可します。許可される品質を制限したい場合は、`next.config.js` に設定を追加できます。

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

上記の例では、25、50、75の3つの品質のみが許可されています。`quality` プロパティがこの配列の値と一致しない場合、画像は400 Bad Request で失敗します。

formats

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

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

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

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

AVIFサポートを有効にできます。これは、ブラウザがAVIFをサポートしていない場合に、`src` 画像の元の形式にフォールバックします。

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

補足:

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

キャッシュの動作

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

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

画像のキャッシュステータスは、`x-nextjs-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を設定できます。
• 複数のフォーマットを無効にし、単一の画像フォーマットを優先するためにformatsを設定できます。

minimumCacheTTL

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

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

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

再検証の回数を減らし、潜在的にコストを削減するためにTTLを増やすことができます。

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

最適化された画像の期限（またはMax Age）は、minimumCacheTTLまたはアップストリーム画像のCache-Controlヘッダーのいずれか大きい方によって定義されます。

画像ごとのキャッシュ動作を変更する必要がある場合は、アップストリーム画像（例: /some-asset.jpgであり、/_next/image自体ではない）にCache-Controlヘッダーを設定するためにheadersを設定できます。

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

disableStaticImages

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

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

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

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

dangerouslyAllowSVG

デフォルトのローダーは、いくつかの理由から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プロップを使用してください。

レスポンシブ画像

デフォルトで生成されるsrcsetには、異なるデバイスピクセル比率をサポートするために1xと2xの画像が含まれています。ただし、ビューポートに合わせて伸縮するレスポンシブ画像をレンダリングしたい場合があるかもしれません。その場合は、sizesとstyle（またはclassName）を設定する必要があります。

以下のいずれかの方法でレスポンシブ画像をレンダリングできます。

静的インポートを使用したレスポンシブ画像

ソース画像が動的でない場合、静的にインポートしてレスポンシブ画像を作成できます。

import Image from 'next/image'
import me from '../photos/me.jpg'
 
export default function Author() {
  return (
    <Image
      src={me}
      alt="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

試してみる

• ビューポートにレスポンシブな画像のデモ

アスペクト比を持つレスポンシブ画像

ソース画像が動的またはリモートURLである場合、レスポンシブ画像の正確なアスペクト比を設定するために、widthとheightも提供する必要があります。

import Image from 'next/image'
 
export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

試してみる

• ビューポートにレスポンシブな画像のデモ

fillを使用したレスポンシブ画像

アスペクト比が不明な場合は、fillプロップを設定し、親要素にposition: relativeを設定する必要があります。オプションとして、目的の引き伸ばし/切り取りの動作に応じてobject-fitスタイルを設定できます。

import Image from 'next/image'
 
export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
      <Image
        src={photoUrl}
        alt="Picture of the author"
        sizes="300px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

試してみる

• fillプロップのデモ

テーマ検出CSS

ライトモードとダークモードで異なる画像を表示したい場合、2つの<Image>コンポーネントをラップし、CSSメディアクエリに基づいて正しい方を表示する新しいコンポーネントを作成できます。

.imgDark {
  display: none;
}
 
@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'
 
type Props = Omit<ImageProps, 'src' | 'priority' | 'loading'> & {
  srcLight: string
  srcDark: string
}
 
const ThemeImage = (props: Props) => {
  const { srcLight, srcDark, ...rest } = props
 
  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

補足：loading="lazy"のデフォルトの動作により、正しい画像のみが読み込まれることが保証されます。priorityまたはloading="eager"を使用することはできません。これらを使用すると両方の画像が読み込まれてしまうためです。代わりに、fetchPriority="high"を使用できます。

試してみる

• ライト/ダークモードテーマ検出のデモ

getImageProps

より高度なユースケースでは、getImageProps()を呼び出して、基となる<img>要素に渡されるプロップスを取得し、それらを別のコンポーネント、スタイル、キャンバスなどに渡すことができます。

これはReactのuseState()の呼び出しも回避するため、パフォーマンスが向上する可能性がありますが、プレースホルダーが削除されないため、placeholderプロップとは併用できません。

テーマ検出Picture要素

ライトモードとダークモードで異なる画像を表示したい場合、ユーザーの優先するカラースキームに基づいて異なる画像を表示するために、<picture>要素を使用できます。

import { getImageProps } from 'next/image'
 
export default function Page() {
  const common = { alt: 'Theme Example', width: 800, height: 400 }
  const {
    props: { srcSet: dark },
  } = getImageProps({ ...common, src: '/dark.png' })
  const {
    props: { srcSet: light, ...rest },
  } = getImageProps({ ...common, src: '/light.png' })
 
  return (
    <picture>
      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
      <source media="(prefers-color-scheme: light)" srcSet={light} />
      <img {...rest} />
    </picture>
  )
}

アートディレクション

モバイルとデスクトップで異なる画像を表示したい場合（これはアートディレクションと呼ばれることもあります）、getImageProps()に異なるsrc、width、height、およびqualityプロップを提供できます。

import { getImageProps } from 'next/image'
 
export default function Home() {
  const common = { alt: 'Art Direction Example', sizes: '100vw' }
  const {
    props: { srcSet: desktop },
  } = getImageProps({
    ...common,
    width: 1440,
    height: 875,
    quality: 80,
    src: '/desktop.jpg',
  })
  const {
    props: { srcSet: mobile, ...rest },
  } = getImageProps({
    ...common,
    width: 750,
    height: 1334,
    quality: 70,
    src: '/mobile.jpg',
  })
 
  return (
    <picture>
      <source media="(min-width: 1000px)" srcSet={desktop} />
      <source media="(min-width: 500px)" srcSet={mobile} />
      <img {...rest} style={{ width: '100%', height: 'auto' }} />
    </picture>
  )
}

背景CSS

srcSet文字列をimage-set() CSS関数に変換して、背景画像を最適化することもできます。

import { getImageProps } from 'next/image'
 
function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}
 
export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }
 
  return (
    <main style={style}>
      <h1>Hello World</h1>
    </main>
  )
}

既知のブラウザバグ

このnext/imageコンポーネントはブラウザネイティブの遅延ロードを使用しており、Safari 15.4より前の古いブラウザでは積極的ロードにフォールバックする場合があります。ぼかしプレースホルダーを使用する場合、Safari 12より前の古いブラウザでは空のプレースホルダーにフォールバックします。width/heightがautoのスタイルを使用する場合、アスペクト比を保持しないSafari 15より前の古いブラウザでは、レイアウトシフトが発生する可能性があります。詳細については、このMDNビデオを参照してください。

• Safari 15 - 16.3では、読み込み中に灰色の枠線が表示されます。Safari 16.4ではこの問題が修正されました。考えられる解決策：
  • CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }を使用する
  • 画像がアバブザフォールドにある場合はpriorityを使用する。
• Firefox 67以降では、読み込み中に白い背景が表示されます。考えられる解決策：
  • AVIF formatsを有効にする。
  • placeholderを使用する。

バージョン履歴