NFT画像が表示されない：メタデータとIPFSの経路を確認する

NFTの保有記録と画像は同じ場所に保存されているとは限りません。画像が見えない場合は、トークンの参照先、メタデータ、画像URI、表示用ゲートウェイを分けて確認します。

参照経路の確認表

コントラクト・token ID → 参照URI → メタデータ → image等のURI → 表示

内容識別と可用性を分ける

IPFSのCIDは内容を識別しますが、永久に取得できるという保証ではありません。公式資料はpinning等による保存・提供の計画を説明しています。一つのゲートウェイの障害と、提供するノードが見つからない状態は別に調べます。

仮の切り分け例

JSONが読めてimageの参照先だけ応答しない例なら、どこまで読めたかを記録し、運営者へCID・パス・時刻を伝えます。署名を求める未知の復旧サイトへ接続する必要はありません。保有記録が残ることだけで画像を復元できると保証しません。

IPFSの資料には終了済みjs-ipfsの旧コードへの注意があります。ここでは参照と読取確認だけを扱い、旧コードを現行実装手順として載せません。

メタデータJSONの中身

ERC-721のメタデータ拡張では、tokenURIの参照先に置くJSONの基本形として、name・description・imageの3項目が示されています。imageには画像のURIが入ります。マーケットプレイスはこのJSONを読み込み、自社のサーバーに画像を保存して表示していることが多いため、元の画像が消えても一覧には古い画像が残る、逆に元は無事でも表示だけ壊れる、ということが起こります。

URIの形で分かること

CIDは「Qm」で始まる旧形式（CIDv0）と「bafy」などで始まる新形式（CIDv1）があり、同じ内容でも見た目が違います。

表示を直したいとき

1. マーケットプレイスの「メタデータを更新（Refresh metadata）」を試す
2. エクスプローラーのRead ContractでtokenURI（ERC-1155はuri）を読み、参照先を直接開く
3. JSONは読めて画像だけ開けないなら、画像のCIDを誰も保存（pin）していない可能性がある。運営に連絡する

出典と確認範囲

• IPFS NFTデータ保存のベストプラクティス
• ERC-721 メタデータ

個別適用や説明の拡張時に確認する事項：規格別のURI、可変データ、保存・提供状況と権利を個別確認。実NFTの復旧は未実施。