Next.js の Image コンポーネントは、リモート画像の許可ホストや最適化設定を、Next.js のビルド工程が生成物へ注入する前提で動く。このコンポーネントを esbuild などで Next.js の外へ単体バンドルすると、画像設定が自動注入されず、外部画像が未許可として扱われることがある。

症状

外部ホストの画像を含むコンポーネントを静的プレビューや単体バンドルで描画すると、画像ホストに関する例外や警告が発生し、場合によってはページ全体が描画されない。実行モードや Next.js のバージョンによって例外と警告の違いがあるため、特定のメッセージだけに依存して判定しない。

対処

プレビュー用途では、アプリ本体より先に評価されるシム層から、Image コンポーネントが必要とする画像設定を与える。実際の画像最適化基盤を再現する必要がない場合は、最適化を無効化し、外部 URL をそのまま画像要素へ渡す構成にする。

設定の内部キーや注入方法は Next.js のバージョンで変わり得るため、特定の内部環境変数名を恒久的な契約として扱わない。利用中バージョンの Image 実装が参照する設定を確認し、必要な既定フィールドをまとめて与える。一部だけを注入すると別の設定欠落で失敗することがある。

ローカルの絶対パス画像や、プレビュー環境から到達できない資産は別問題として扱い、相対パスへの変換、埋め込み、またはプレビュー用資産への置換を行う。

検証

許可リスト外の外部画像を含む代表コンポーネントを実際に単体レンダリングし、ページが空白にならないこと、画像要素が生成されること、コンソールに画像設定由来の例外がないことを確認する。Next.jsを更新したときも同じ実レンダリングを回帰確認する。