Next.jsのImageコンポーネントで「missing required 'width' property」エラーの解決法

問題説明

Next.jsアプリケーションでnpm run devを実行すると、next/imageのImageコンポーネントが「missing required "width" property」というエラーを発生させる場合があります。このエラーは、次のような特徴を持っています：

必須プロパティ不足: Imageコンポーネントにwidthとheightのプロパティが適切に指定されていない場合に発生
CSSでは解決不可: 外部CSSファイルで幅や高さを指定しても修正されない
インライン属性で一時回避可能: すべてのImageコンポーネントにインラインでwidthとheightを設定するとエラーを回避可能

典型的なエラーメッセージ:

Error: Image with src "https://example.com/image.png" is missing required "width" property.

このエラーの根本原因は、Next.jsのImageコンポーネントが画像のレイアウトサイズを事前に把握する必要があるためです。

解決方法

以下に効果的な解決策を紹介します。状況に応じて適切な方法を選択してください。

1. `fill`プロパティの使用（推奨）

Imageコンポーネントにfillプロパティを追加し、親要素でサイズを制御する方法：

jsx

<div className="relative h-80 w-full"> {/* 親要素でサイズを定義 */}
  <Image
    src="/example-image.jpg"
    alt="説明テキスト"
    fill // 親要素にフィットさせる
    className="object-cover" // アスペクト比を維持
  />
</div>

ポイント

親要素にposition: relative（className="relative"）を指定
親要素でwidthとheightを明示的に定義
object-fit（contain, coverなど）で画像の調整方法を指定

2. 明示的な幅・高さの指定

画像サイズが固定の場合は直接指定：

jsx

<Image
  src="/static-logo.png"
  alt="ロゴ"
  width={300} // 必須プロパティ
  height={150} // 必須プロパティ
/>

注意

外部URLの画像を使用する場合、Next.jsはデフォルトで画像サイズを把握できません：

jsx

<Image
  src="https://external-site.com/image.jpg"
  width={800} // 明示的に指定必須
  height={600}
  alt="外部画像"
/>

3. `fill`使用時の特殊ケース対応

fill使用時に画像がabsolute位置になるのを防ぐには：

jsx

<div className="relative">
  <Image
    src="/background.jpg"
    alt="背景画像"
    fill
    className="!relative" // 絶対位置を上書き
  />
</div>

4. 動的画像サイズの計算（外部画像用）

外部サイトの画像でサイズが不明な場合：

jsx

<Image
  src="https://external.com/dynamic-image.png"
  alt="動的画像"
  width={800}
  height={600}
  loader={({ src }) => `${src}?w=800&h=600`} // サイズパラメータ追加
/>

よくある落とし穴と回避策

親要素のサイズ未定義問題

fillプロパティを使用しているのに親要素にサイズ指定がない場合、画像が表示されないことがあります：

jsx

<div className="relative"> {/* 高さ指定なし */}
  <Image src="/..." alt="..." fill />
</div>

jsx

<div className="relative h-[300px]"> {/* 高さ明示 */}
  <Image src="/..." alt="..." fill />
</div>

グリッドレイアウトでのサイズ継承問題

グリッドシステム内で親要素が相対的なサイズを持つ場合：

jsx

<div className="grid grid-cols-2">
  <div>コンテンツの高さが基準になる</div>
  <div className="relative"> {/* 兄弟要素の高さを継承 */}
    <Image src="/..." alt="..." fill />
  </div>
</div>

TIP

fillプロパティ使用中にposition: relativeを直接適用しようとするとエラーが発生します。代わりにclassNameで適用すると安全です

ベストプラクティス

ローカル画像最適化:

jsx

import localImage from '@/assets/image.jpg';
<Image src={localImage} alt="最適化済み画像" />

パフォーマンス重視の属性設定:

jsx

<Image
  src="/hero.jpg"
  priority // 重要画像の優先ロード
  quality={85} // 画質最適化
/>

レスポンシブ対応:

jsx

<div className="relative w-full aspect-[16/9]">
  <Image src="/..." alt="レスポンシブ画像" fill />
</div>

テスト環境での対処法

Jestテスト中に発生する場合、モック実装で解決：

jsx

// jest.setup.js
jest.mock('next/image', () => ({
  __esModule: true,
  default: (props) => <img {...props} />, // シンプルなimgタグで置換
}));

実際のアプリケーション実行時には影響しないため、テスト専用の解決策として有効です。

まとめ

next/imageで「missing required 'width' property」エラーを解決する鍵は：

手法	用途
`fill`プロパティ	親要素に基づく柔軟なサイジング
明示的`width`/`height`	固定サイズ画像に最適
`loader`のカスタマイズ	外部画像のサイズ指定問題解決
親要素のサイズ制御	`fill`使用時の基盤

next/imageの公式ドキュメントも常に最新情報を確認してください：Next.js Image Component Docs

関連記事

Next.jsのImageコンポーネントで「missing required 'width' property」エラーの解決法 ​

問題説明 ​

解決方法 ​

1. fillプロパティの使用（推奨） ​

2. 明示的な幅・高さの指定 ​

3. fill使用時の特殊ケース対応 ​

4. 動的画像サイズの計算（外部画像用） ​

よくある落とし穴と回避策 ​

親要素のサイズ未定義問題 ​

グリッドレイアウトでのサイズ継承問題 ​

ベストプラクティス ​

テスト環境での対処法 ​

まとめ ​