VSCodeで画像が表示されない場合、画像ファイルそのものに問題があるとは限りません。
実際には、画像へのパス指定やファイル名、Markdown・HTML・CSSの記述、拡張機能、Remote環境など、さまざまな原因が考えられます。
特に多いのが、画像の保存場所とソースコードで指定しているパスが一致していないケースです。
まずは次のようなポイントを確認すると、原因を効率よく特定できます。
- 画像ファイルが存在しているか
- ファイル名や拡張子が正しいか
- 大文字と小文字が一致しているか
- 相対パスが正しく指定されているか
- MarkdownやHTMLの記述が正しいか
- ブラウザで404エラーが発生していないか
- 拡張機能が干渉していないか
- Remote環境のファイル位置が正しいか
表示されない場所によって確認すべきポイントも異なります。
VSCodeで画像ファイルを直接開いても表示されないのか、Markdownプレビューだけで表示されないのか、HTMLをブラウザで開いた場合だけ表示されないのかを最初に確認するとよいでしょう。
画像ファイルへのパスが間違っている
VSCodeで画像が表示されない原因として特に多いのが、画像へのパス指定の間違いです。
Markdownで画像を表示する場合
Markdownでは、一般的に次の形式で画像を指定します。
たとえば、フォルダ構成が次のようになっているとします。
project/
├─ README.md
└─ images/
└─ sample.png
この場合、README.mdからsample.pngを表示するには、次のように指定できます。
または、
と記述することもできます。
一方、次のように記述すると、
VSCodeは基本的にREADME.mdと同じ階層からsample.pngを探します。
実際の画像がimagesフォルダ内にある場合は、表示されません。
相対パスの指定方法を確認する
画像が表示されない場合は、相対パスの考え方を理解しておくことが重要です。
Markdownファイルと画像が同じフォルダにある場合
project/
├─ README.md
└─ sample.png
この場合は、次のように指定できます。
子フォルダに画像がある場合
project/
├─ README.md
└─ images/
└─ sample.png
この場合は、
と指定します。
親フォルダ側に画像がある場合
project/
├─ images/
│ └─ sample.png
└─ docs/
└─ README.md
docs/README.mdから画像を参照する場合は、
と記述します。
..は1つ上の階層を意味します。
画像が表示されない場合は、VSCodeのエクスプローラーでフォルダ構成を確認しながらパスを見直すと原因を発見しやすくなります。
ファイル名や拡張子が間違っていないか確認する
画像へのパスが正しくても、ファイル名や拡張子が間違っていると表示されません。
画像の拡張子を確認する
たとえば、実際のファイル名が、
sample.jpg
なのに、
と指定していれば、画像は表示されません。
よく使われる画像形式には次のようなものがあります。
.png
.jpg
.jpeg
.gif
.webp
.svg
Windowsでは、エクスプローラーの設定によって拡張子が非表示になっていることがあります。
そのため、
sample.png
だと思っていたファイルが、実際には、
sample.png.jpg
になっている可能性もあります。
画像が表示されない場合は、実際の拡張子まで確認してみましょう。
大文字と小文字を確認する
Windowsでは気づきにくい問題ですが、Linux環境やWebサーバーではファイル名の大文字と小文字が区別されることがあります。
たとえば、実際の画像ファイルが、
Sample.png
なのに、
<img src="./sample.png" alt="">
と記述している場合、環境によっては画像が表示されません。
正しくは、
<img src="./Sample.png" alt="">
のように、実際のファイル名と完全に一致させます。
ローカルのWindows環境では表示できるのに、LinuxサーバーやGitHub Pagesへ公開すると画像が表示されなくなった場合は、大文字と小文字を確認してみましょう。
Markdownプレビューで画像が表示されない場合
Markdownファイル内の画像が表示されない場合は、Markdownの記述や画像へのパスを確認します。
Markdownプレビューを開く
Windows・Linuxでは、
Ctrl + Shift + V
を押すとMarkdownプレビューを開けます。
Macでは、
Command + Shift + V
です。
エディター横にプレビューを開いて確認する方法もあります。
Markdownの画像記法を確認する
基本的な記述方法は次のとおりです。
画像の場所と指定したパスが一致しているか確認してください。
特に、Windowsの絶対パスを直接記述するより、プロジェクト内に画像を保存し、相対パスで管理するほうが扱いやすくなります。
参考サイト
Markdownのパス補完を利用する
画像へのパスを手入力すると、フォルダ名やファイル名を間違える可能性があります。
VSCodeにはMarkdown内のパス補完機能があります。
たとえば、
![画像](./images/
まで入力すると、画像ファイルなどの候補を表示できます。
必要に応じて、
Ctrl + Space
で補完候補を表示することもできます。
手入力だけに頼らず、補完機能を使用することでパスミスを減らせます。
Markdownのリンク検証を有効にする
VSCodeには、Markdown内のリンクや画像のパスを検証する機能があります。
ただし、この機能はデフォルトでは無効です。
設定ファイルに次のように記述すると有効にできます。
{
"markdown.validate.enabled": true
}
有効にすると、存在しない画像やファイルへのリンクを検出しやすくなります。
Markdownファイルを頻繁に扱う場合は便利な設定です。
Markdownへ画像をドラッグ＆ドロップする
VSCodeでは、Markdownへ画像を手作業で指定するだけでなく、画像をドラッグ＆ドロップしたり、クリップボードから貼り付けたりすることもできます。
また、コマンドパレットから、
Markdown: Insert Image from Workspace
を利用して画像を挿入する方法もあります。
パスを自分で入力する必要が少なくなるため、入力ミスの防止にも役立ちます。
HTMLで画像が表示されない場合
HTMLの場合は、imgタグのsrc属性を確認します。
imgタグのパスを確認する
基本的な記述例は次のとおりです。
<img src="./images/sample.png" alt="サンプル画像">
フォルダ構成が、
project/
├─ index.html
└─ images/
└─ sample.png
であれば、この指定で問題ありません。
一方、
project/
├─ images/
│ └─ sample.png
└─ pages/
└─ index.html
の場合は、
<img src="../images/sample.png" alt="サンプル画像">
と指定する必要があります。
HTMLファイルから見て、画像がどこにあるのかを基準にパスを考えることが重要です。
「/images」と「./images」の違いに注意する
次の2つは似ていますが、意味が異なります。
<img src="./images/sample.png" alt="">
<img src="/images/sample.png" alt="">
./images/sample.pngは、現在のHTMLファイルの位置を基準とした相対URLです。
一方、
/images/sample.png
は、Webサイトのルートを基準とするURLです。
そのため、サイトがサブディレクトリ配下に公開されている場合には、/images/sample.pngが意図した場所を参照しないことがあります。
ローカル開発やGitHub Pagesなどでは、この違いに注意しましょう。
CSSのbackground-imageが表示されない場合
CSSで背景画像を指定している場合は、HTMLではなくCSSファイルの位置を基準に考える必要があります。
CSSファイルから見た相対パスを確認する
たとえば、次のフォルダ構成があるとします。
project/
├─ index.html
├─ css/
│ └─ style.css
└─ images/
└─ background.jpg
style.cssからbackground.jpgを参照する場合は、
.hero {
background-image: url("../images/background.jpg");
}
と指定します。
次のように、
background-image: url("./images/background.jpg");
としてしまうと、css/images/background.jpgを探すことになるため、画像が表示されません。
HTMLファイルではなく、CSSファイルの場所を基準にする点が重要です。
画像ファイルをVSCodeで直接開いて確認する
原因を切り分けるためには、対象の画像ファイルをVSCodeで直接開いてみる方法が有効です。
直接表示できる場合
VSCodeのエクスプローラーから画像ファイルをクリックし、正常に表示できるのであれば、画像ファイル自体には大きな問題がないと考えられます。
この場合は、
- パス
- Markdown
- HTML
- CSS
などの記述を重点的に確認します。
直接表示できない場合
画像ファイルを直接開いても表示できない場合は、
- ファイルが破損している
- 実際の画像形式と拡張子が一致していない
- 一般的でない画像形式を使用している
などの可能性があります。
Windowsのフォトアプリやブラウザなど、別のアプリでも画像を開いて確認してみましょう。
画像ファイルが破損していないか確認する
画像そのものが破損しているケースもあります。
VSCodeだけでなく、WindowsのフォトアプリやMacのプレビュー、Webブラウザなどでも開けない場合は、画像ファイル自体に問題がある可能性が高いでしょう。
その場合は、
- 元画像から再度書き出す
- PNGへ変換する
- JPEGへ変換する
- WebPへ変換する
などの方法を試します。
ファイル名に特殊文字が含まれていないか確認する
日本語やスペースを含むファイル名でも、適切に処理されれば画像を表示できます。
そのため、特殊文字が含まれているから必ず表示できないというわけではありません。
ただし、
商品画像 01.png
画像#01.png
photo?.png
のような名前は、URLエンコードや環境の違いによってトラブルの原因になることがあります。
Web制作では、
product-image-01.png
のように、
- 半角英数字
- ハイフン
- アンダースコア
を中心にしたファイル名にすると、トラブルを減らしやすくなります。
Live Serverで画像が表示されない場合
VSCodeでWeb制作をしている場合、Live ServerなどでHTMLを表示することがあります。
HTMLは表示できるのに画像だけ表示されない場合は、ブラウザの開発者ツールを確認しましょう。
404エラーを確認する
Chromeなどでは、
F12
または、
Ctrl + Shift + I
で開発者ツールを開けます。
「Network」タブを開き、ページを再読み込みします。
画像のリクエストに、
404 Not Found
が表示されている場合は、指定したURLに画像が存在していない可能性が高いです。
この場合は、
src- CSSの
url() - フォルダ名
- ファイル名
- 拡張子
- 大文字と小文字
を確認します。
403エラーの場合
画像へのアクセスが、
403 Forbidden
になっている場合は、単純なパスミスではなく、Webサーバー側のアクセス制限や権限設定などが原因になっている可能性があります。
VSCodeの拡張機能が原因の場合
Markdownや画像プレビューに関係する拡張機能が干渉している可能性もあります。
拡張機能を一時的に無効化する
特に、
- Markdown関連
- HTMLプレビュー関連
- Preview関連
- Webviewを使用する拡張機能
などを多数利用している場合は確認してみましょう。
拡張機能を一時的に無効化して正常に表示されるか確認すると、原因を切り分けられます。
Extension Bisectを利用する
VSCodeには、問題を起こしている拡張機能を絞り込むための「Extension Bisect」という機能もあります。
拡張機能を多数インストールしている場合は、1つずつ手動で無効化するより効率的です。
VSCodeを再読み込みする
VSCodeの一時的な表示不具合であれば、ウィンドウを再読み込みすると改善することがあります。
コマンドパレットを、
Ctrl + Shift + P
で開き、
Developer: Reload Window
を実行します。
ただし、画像へのパスそのものが間違っている場合は、再読み込みしても改善しません。
あくまで一時的な描画や拡張機能の状態をリセットする方法として利用します。
VSCodeを更新する
長期間VSCodeをアップデートしていない場合は、最新版への更新も検討しましょう。
画像プレビューやMarkdown関連の機能はアップデートによって改善されることがあります。
一方、更新直後から問題が発生した場合は、VSCode本体だけでなく、使用している拡張機能との互換性も確認するとよいでしょう。
Webviewで画像が表示されない場合
VSCode拡張機能を開発している場合は、通常のHTMLとは異なる注意点があります。
VSCodeのWebviewはセキュリティ上分離された環境で動作します。
そのため、ローカル画像へのパスをそのまま指定するだけでは表示できないことがあります。
asWebviewUriを使用する
Webviewからローカルリソースを読み込む場合は、webview.asWebviewUriを使用します。
たとえば、
const onDiskPath = vscode.Uri.joinPath(
extensionUri,
"media",
"sample.png"
);
const imageUri = panel.webview.asWebviewUri(onDiskPath);
のようにURIを変換し、
<img src="${imageUri}" alt="">
として利用します。
VSCode拡張機能のWebviewを開発している場合は重要なポイントです。
localResourceRootsを確認する
Webviewでは、読み込み可能なローカルリソースの範囲をlocalResourceRootsで制限できます。
画像ファイルが許可された範囲外にある場合は、正しいURIを指定していても読み込めない可能性があります。
Webviewで画像が表示されない場合は、
asWebviewUriを使用しているかlocalResourceRootsの範囲内にあるか- Content Security Policyでブロックされていないか
を確認しましょう。
Content Security Policyを確認する
Webviewでは、Content Security Policyによって読み込めるリソースを制限できます。
画像の読み込み元がCSPで許可されていない場合、画像のパスが正しくても表示されません。
そのため、Webview開発では、
asWebviewUri
↓
localResourceRoots
↓
Content Security Policy
という順番で確認すると原因を特定しやすくなります。
Remote SSHやWSLで画像が表示されない場合
VSCodeでは、Remote SSH、WSL、Dev Containers、GitHub Codespacesなどを利用できます。
ローカルとリモートのファイル位置を確認する
Remote環境では、
Windows側のファイル
と、
WSL・コンテナ・リモートサーバー側のファイル
が同じ場所に存在するとは限りません。
たとえば、HTMLファイルがリモートサーバー上にあるのに、画像だけローカルPCに存在している場合、そのHTMLから直接画像を参照できないことがあります。
ただし、Remote環境を使用しているだけで画像が表示されなくなるわけではありません。
正しい場所にファイルがあり、正しいパスを指定していれば、通常のMarkdownやHTML画像は利用できます。
Remote環境ではWebサーバーのポートも確認する
Remote SSHやDev Containers内でWebサーバーを起動している場合は、ポートフォワーディングの設定も確認しましょう。
画像だけでなくCSSやJavaScriptも読み込めない場合は、画像パスではなくWebサーバーへの接続そのものに問題がある可能性があります。
GitHub Pagesで画像が表示されない場合
ローカルでは表示できるのにGitHub Pagesなどへ公開すると画像が表示されなくなることがあります。
大文字と小文字を確認する
Linuxベースの環境では、
Image.png
と、
image.png
は別のファイルとして扱われることがあります。
ローカルで動作していても、公開環境で表示されない場合は確認しましょう。
ルート相対URLを確認する
次のような指定は、
<img src="/images/photo.png" alt="">
Webサイトのルートを基準にします。
GitHub Pagesのプロジェクトサイトなど、サブディレクトリ配下に公開されるサイトでは、意図したパスと異なることがあります。
画像がGitへ追加されているか確認する
画像ファイルをPC上に作成しただけでは、GitHub上には存在しません。
次のコマンドで確認できます。
git status
必要に応じて、
git add images/photo.png
git commit -m "Add image"
git push
などを実行します。
.gitignoreによって画像フォルダが除外されていないかも確認しましょう。
VSCodeで画像が表示されないときの確認手順
原因が分からない場合は、次の順番で確認すると効率的です。
1. 画像ファイルが存在するか確認する
VSCodeのエクスプローラーから、対象の画像ファイルが実際に存在しているか確認します。
2. 画像を直接開く
VSCodeで画像ファイルを直接開きます。
表示できない場合は、画像ファイル自体に問題がある可能性があります。
3. ファイル名と拡張子を確認する
sample.png
なのか、
sample.jpg
なのかを確認します。
大文字と小文字も一致させます。
4. 相対パスを確認する
Markdownなら、
HTMLなら、
<img src="./images/sample.png" alt="">
など、実際のフォルダ構成と一致しているか確認します。
5. ブラウザのNetworkを確認する
Webページの場合は開発者ツールを開き、画像のリクエストが404になっていないか確認します。
6. VSCodeを再読み込みする
一時的な表示エラーを疑う場合は、
Developer: Reload Window
を実行します。
7. 拡張機能を確認する
拡張機能を一時的に無効化したり、Extension Bisectを利用したりして原因を切り分けます。
8. Remote環境を確認する
WSLやSSH、Dev Containersを使用している場合は、画像とソースファイルがどの環境に存在しているか確認します。
VSCodeで画像が表示されない場合はパスから確認する
VSCodeで画像が表示されない原因として最も多いのは、画像ファイルへのパス指定です。
そのため、トラブルが発生した場合は、
画像ファイルが存在するか
↓
画像を直接開けるか
↓
ファイル名・拡張子
↓
大文字・小文字
↓
相対パス
↓
ブラウザの404
↓
VSCodeや拡張機能
↓
Remote環境
↓
Webview固有の制限
という順番で確認すると、原因を特定しやすくなります。
Markdownの場合はVSCodeのパス補完やリンク検証、画像のドラッグ＆ドロップなども利用できます。
HTMLやCSSの場合は、どのファイルを基準に相対パスが解決されるのかを意識することが重要です。
また、VSCode拡張機能のWebviewで画像が表示されない場合は、通常のWebページとは異なり、asWebviewUriやlocalResourceRoots、Content Security Policyなどの確認も必要になります。
まずは画像ファイルそのものに問題があるのか、それとも画像を参照しているパスや表示環境に問題があるのかを切り分けることが、解決への近道です。
以上、VSCodeで画像が表示されない主な原因についてでした。
最後までお読みいただき、ありがとうございました。
