Next.jsで「Image Optimization using Next.js default loader is not compatible with next export」エラー

2025.09.11

Next.js を使った開発で静的サイトを生成する際に next export を実行すると、以下のようなエラーに遭遇することがあります。

Error: Image Optimization using Next.js' default loader is not compatible with `next export`.
Possible solutions:
- Use `next start` to run a server, which includes the Image Optimization API.
- Configure `images.unoptimized = true` in `next.config.js` to disable the Image Optimization API.

これは Next.js の Image コンポーネントが標準で提供する画像最適化機能が、静的エクスポートと両立できないことが原因です。ここでは原因の整理と、実際の解決策を技術者向けに詳しく解説します。

目次

1. エラーの原因を理解する

Next.js の Image コンポーネントは、実行時にサーバー側で画像を最適化する API を呼び出します。

しかし next export は完全に静的な HTML を生成するため、この API が利用できずエラーとなります。したがって、静的ホスティング（Netlify や GitHub Pages など）にデプロイする場合は、この機能をオフにする必要があります。

特に Next.js 12 以降では画像最適化機能がデフォルトで有効になっており、開発環境では動作しても本番ビルド時に初めてエラーになるケースがあります。エラーメッセージが示している通り、解決には サーバーを立てる か 画像最適化を無効化する のどちらかを選択することになります。

2. images.unoptimized オプションでの解決

もっとも簡単な方法は、Next.js の設定ファイル next.config.js に images.unoptimized = true を追加することです。これにより Image コンポーネントは単なる <img> タグとして出力され、ビルド時にエラーが発生しなくなります。

// next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
};

この設定は全ての画像最適化を無効にするため、最終的なファイルサイズが大きくなる可能性があります。もし大量の画像を扱うプロジェクトであれば、ビルド前に自前で画像圧縮を行う（例えば imagemin や Squoosh CLI を利用する）と良いでしょう。

3. 外部ローダーを設定する方法

Next.js では独自のローダーを設定することも可能です。たとえば画像を CDN に配置している場合は、loader と path を指定することで外部ホスティングを利用できます。

// next.config.js
module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example-cdn.com/',
  },
};

この方法では Next.js のサーバー機能を使わずに、外部サービスによる最適化を活用できます。Cloudinary や Imgix などの画像最適化サービスを利用している場合に有効です。

ただし、外部ローダーの仕様に合わせて URL を組み立てる必要があるため、導入時にはドキュメントをしっかり確認しましょう。

4. 具体的な失敗例と回避策

よくある失敗として、開発環境では next dev で動いていたのに、本番で next export した途端にサイトが真っ白になるというケースがあります。

これはビルド時に上記エラーが発生しており、出力が中断されるためです。CI/CD パイプラインで自動デプロイをしている場合、ビルドログを必ず確認し、エラーを見逃さないようにしましょう。

さらに、unoptimized 設定を忘れているとビルドは通っても画像が表示されない、もしくは 404 になることがあります。ローカルで next build && next export を実行して事前に動作確認するのが安全です。

5. 画像管理のベストプラクティス

静的サイトとしてデプロイする場合、画像最適化はビルド前に済ませておくのが理想です。以下のようなフローを採用すると、CI/CD 環境でも安定して動作します。

  • 画像は public ディレクトリに配置する
  • ビルド前にスクリプトで画像をリサイズ・圧縮する
  • images.unoptimized = true を設定し、ビルドエラーを防ぐ
  • CDN を利用する場合はキャッシュ戦略も合わせて検討する

こうすることで、Next.js の Image コンポーネントを使いつつ静的エクスポートを成功させることができます。

6. まとめ

next export 実行時に発生する「Image Optimization using Next.js default loader is not compatible」エラーは、Next.js が提供する画像最適化機能と静的エクスポートの仕様が噛み合わないことが原因です。

解決するには images.unoptimized 設定を有効にするか、外部ローダーを設定するのが一般的です。プロジェクトの要件によっては自前で画像最適化パイプラインを構築することも検討すべきでしょう。重要なのは、開発環境だけでなく本番ビルドでも必ず挙動を確認し、CI/CD で問題が起きないようにすることです。

参考

タイトルとURLをコピーしました