Base64 画像が表示されない？よくある 10 の原因と修正方法

画像を Base64 に変換し、data URI を HTML に挿入した──なのに何も表示されない。壊れた画像アイコンがぽつんと表示されるだけ。さらに厄介なことに、Chrome では表示されるのに Safari では真っ白、ローカルでは動くのに本番ではダメ、ということもあります。

Base64 画像の表示失敗がもどかしいのは、文字列が一見正しく見えるからです。本当の原因は細部に潜んでいます──プレフィックスの 1 文字の欠落、コピペ時に紛れ込む不可視の空白、バックエンドが知らぬ間に行う二重エンコード。この記事では 10 の原因すべてをコード例と修正方法付きで解説します。

クイックリファレンス：症状 → 原因 → 修正

まずここから。自分の症状を見つけ、原因を特定し、下の詳細な修正方法にジャンプしてください。

プレフィックスの誤り：data: URI が不正

data URI の構文は厳密です。1 文字間違えるだけで、ブラウザは Base64 文字列を画像データではなく壊れた URL として扱います。

原因 1：data URI プレフィックスがまるごと欠落

生の Base64 文字列を data:image/...;base64, プレフィックスなしで直接 src に設定すると、ブラウザはそれを相対 URL パスと解釈し、結果は 404 になります。

❌ <img src="iVBORw0KGgo..." />
✅ <img src="data:image/png;base64,iVBORw0KGgo..." />

原因 2：セミコロンをカンマと誤記

data:image/png;base64,... ではなく data:image/png,base64,... と書くと、ブラウザは base64,... を Base64 エンコードの指示ではなくプレーンテキストとして扱います。

❌ data:image/png,base64,iVBORw0KGgo...
✅ data:image/png;base64,iVBORw0KGgo...

原因 3："base64" の後のカンマが欠落

base64 と実際のデータの間のカンマは必須です。data:image/png;base64iVBOR... のように省略すると、ブラウザは base64iVBOR... を文字セット名と解釈します。

❌ data:image/png;base64iVBORw0KGgo...
✅ data:image/png;base64,iVBORw0KGgo...

エンコーディング破損：Base64 文字列自体が壊れている

プレフィックスが正しくても、エンコード済みデータは保存・転送・コピペの過程で知らぬ間に破損することがあります。

原因 4：文字列の切り詰め

データベースのカラムに文字数制限（例: VARCHAR(65535)）があると、Base64 文字列がサイレントに切り詰められます。100KB の PNG は Base64 で約 136,000 文字。65,535 文字で切り詰められると、デコード後の画像は完全に壊れます。修正：Base64 の保存には TEXT または LONGTEXT 型を使用してください。

原因 5：不正な文字の混入（空白・特殊文字）

有効な Base64 は A-Z、a-z、0-9、+、/、= のみで構成されます。コピペ時に混入した空白は atob() の InvalidCharacterError を引き起こします。修正：使用前にすべての空白を除去: str.replace(/\s/g, '')。

原因 6：改行文字の混入

openssl base64 はデフォルトで 76 文字ごとに \n を挿入します（RFC 2045 準拠）。これらの改行は HTML の data URI を壊します。修正：openssl base64 -A（一行出力）を使うか、改行を除去: str.replace(/[\r\n]/g, '')。

原因 7：URL 解析でパディングが消失

Base64 末尾のパディング文字 = は URL パラメータを経由すると消失しがちです（= は URL の予約文字のため）。パディングなしでも動くブラウザとそうでないブラウザがあり、環境間で挙動が不一致になります。修正：URL に含める前に encodeURIComponent() を使うか、受信側でパディングを補完してください。

MIME タイプ不一致：本当に壊れるのか？

意外かもしれませんが、MIME タイプを間違えて宣言しても、ほとんどの場合画像は正常に表示されます。

原因 8：宣言した MIME と実際のファイル形式が不一致

data:image/png;base64,/9j/4AAQ...（JPEG データに PNG の MIME を宣言）と書いても、ほとんどのモダンブラウザはコンテンツスニッフィングで正しくレンダリングします。ただし 2 つのケースでは問題になります：(1) 厳格な CSP で MIME を強制している場合、(2) サーバー側が宣言された MIME でフォーマット変換を行う場合。結論：正しく直すべきですが、表示失敗の原因であることは稀です。

パイプラインの問題：ブラウザに届く前にデータが壊れている

このカテゴリは最も診断が難しい──コード上の Base64 文字列は正しく見えるのに、シリアライズや転送の過程で破損が発生しています。

原因 9：Base64 の二重エンコード

バックエンドがすでにエンコード済みのデータをさらに Base64 エンコードすると、Base64 文字列をもう一度 Base64 したものが生成されます。長さが想定より ~33% 多くなり、一度デコードしてもバイナリ画像データではなくテキストが得られます。見分け方：一度デコードし、結果がまた Base64 文字列のように見える（英字で始まり = で終わる）なら二重エンコードです。修正：バックエンド処理から余分なエンコードを削除してください。

原因 10：JSON エスケープまたは URL エンコーディング汚染

Base64 文字列には / が含まれます。一部の JSON シリアライザはこれを \/ にエスケープします。フロントエンドが JSON.parse を使わず生の文字列を取得すると、余分なバックスラッシュがデータを汚染します。同様に、URL パラメータ経由で Base64 を渡すと + がスペースに、= が消失します。修正：JSON データには必ず JSON.parse() を使用。URL 経由の場合は encodeURIComponent() を使用してください。

体系的デバッグテンプレート

上記のどれにも該当しない場合、以下の手順で切り分けてください：

1. ブラウザのアドレスバーで data URI をテスト ── 完全な data:image/...;base64,... 文字列をアドレスバーに直接貼り付けます。表示されれば、アプリケーション側の文字列注入に問題があります。
2. ブラウザコンソールを確認 ── F12 を押して Console タブで net::ERR_INVALID_URL や CSP 違反のエラーを探します。
3. 文字列の長さを照合 ── ソース（バックエンド）とフロントエンドで受け取った Base64 文字列の長さを比較します。不一致があれば転送中の切り詰めか破損です。
4. デコードして検査 ── コンソールで atob() を使い最初の数文字をデコードします。InvalidCharacterError が出れば不正な文字が混入しています。
5. 二重エンコードを検出 ── 一度デコードし、結果がまだ Base64 文字列のように見えたらもう一度デコードします。二回目で二進データが得られれば、処理パイプラインに余分なエンコード工程があります。

ViewJSON で Base64 を即座に検証

Base64 文字列を手動で検証する代わりに、JSON を ViewJSON に貼り付けてください。マジックナンバー検出で Base64 エンコードメディアを自動識別し、インラインプレビューを表示します──プレビューが表示されれば Base64 は有効。表示されなければ、どのフィールドが壊れているか正確に特定できます。