VSCodeでHTMLファイルを作成していると、「プレビューが表示されない」「画面が真っ白になる」「CSSやJavaScriptが反映されない」といったトラブルが起こることがあります。
原因はHTMLそのものの記述ミスだけとは限りません。
ファイル形式、VSCodeのプレビュー方法、拡張機能、相対パス、JavaScriptエラー、ローカルサーバー、リモート開発環境など、さまざまな要因が考えられます。
原因を一つずつ切り分けて確認することが大切です。
HTMLファイルとして正しく認識されていない
ファイルの拡張子を確認する
まず確認したいのが、対象ファイルがHTMLファイルとして保存されているかどうかです。
通常は、次のようなファイル名にします。
index.html
または、
index.htm
一方、次のようなファイル名になっていると、HTMLファイルとして正しく扱われない可能性があります。
index
index.html.txt
index.htm.txt
Windowsではファイル拡張子が非表示になっていることもあるため、実際にはindex.html.txtになっていないか確認しましょう。
VSCodeの言語モードを確認する
VSCodeの画面右下には、現在のファイルをどの言語として認識しているかが表示されています。
HTMLファイルを開いている場合は、基本的に「HTML」と表示されます。
「Plain Text」などになっている場合は、右下の言語モードをクリックして「HTML」を選択します。
HTMLのプレビュー方法を間違えている
Markdownのプレビュー機能とは異なる
VSCodeにはMarkdown用のプレビュー機能があります。
WindowsやLinuxでは、一般的に次のショートカットでMarkdownプレビューを表示できます。
Ctrl + Shift + V
しかし、この機能はMarkdown向けであり、HTMLプレビューとは別の機能です。
そのため、HTMLファイルを開いた状態で同じショートカットを押しても、期待したHTMLプレビューが表示されないことがあります。
Integrated BrowserからHTMLを開く
現在のVSCodeにはIntegrated Browserが用意されており、HTMLファイルをVSCode内で確認できます。
HTMLファイルを開き、右クリックメニューなどから、
Open in Integrated Browser
を選択すると、VSCode内にHTMLページを表示できます。
VSCodeのバージョンによってメニューの表示位置や利用できる機能が異なる場合があるため、項目が見つからない場合はVSCodeを最新版へ更新してみましょう。
VSCodeのバージョンが古い
古い解説記事と現在の仕様が異なる場合がある
VSCodeは頻繁にアップデートされているため、数年前の解説記事と現在の操作方法が異なることがあります。
特にHTMLプレビューについては、Integrated Browser関連の機能が追加・改善されています。
そのため、
「解説記事に書かれているボタンがない」
「同じ操作をしてもプレビューが表示されない」
という場合は、VSCodeのバージョンの違いを確認してみましょう。
Windowsでは、メニューから、
Help
↓
About
などを開くとバージョンを確認できます。
Live Previewがインストールされていない
Live PreviewはMicrosoft提供の拡張機能
HTMLをローカルサーバー経由で確認したい場合は、Microsoftが提供している「Live Preview」拡張機能を利用できます。
VSCode左側のExtensionsを開き、
Live Preview
と検索します。
発行元がMicrosoftであることを確認してインストールします。
Live Previewを利用すると、HTMLファイルをローカルサーバー経由で表示できるため、通常のブラウザに近い環境で動作確認できます。
ただし、Live PreviewはVSCode本体の標準機能ではありません。
整理すると、次のような違いがあります。
Integrated Browser
→ VSCode本体の機能
Live Preview
→ Microsoftが提供している拡張機能
参考サイト
VSCode「Live Preview」の使い方完全ガイドHTML・CSS・JSを即時プレビュー – きになる～
Live Previewが無効になっている
拡張機能の有効状態を確認する
Live Previewをインストールしていても、拡張機能が無効化されている場合は利用できません。
ExtensionsからLive Previewを開き、「Enable」が表示されていないか確認します。
また、VSCodeではワークスペース単位で拡張機能を無効化できます。
そのため、
「別のプロジェクトでは使えるのに、このプロジェクトでは使えない」
という場合は、ワークスペースだけでLive Previewが無効化されていないか確認してみましょう。
プロジェクトフォルダを開いていない
HTMLファイル単体でも利用できる
Live Previewは、必ずしもプロジェクトフォルダを開かなければ利用できないわけではありません。
HTMLファイル単体でもプレビューできる場合があります。
ただし、Web制作ではプロジェクトのルートフォルダをVSCodeで開いたほうが、CSSやJavaScript、画像などのパスを管理しやすくなります。
たとえば、次のような構成があるとします。
my-site/
├── index.html
├── css/
│ └── style.css
├── js/
│ └── main.js
└── images/
└── logo.png
この場合は、index.htmlだけを開くのではなく、my-siteフォルダ全体をVSCodeで開くのがおすすめです。
メニューから、
File
↓
Open Folder
を選択してプロジェクトフォルダを開きます。
HTMLファイルが保存されていない
更新されない場合は一度保存して確認する
使用しているプレビュー方法や設定によって、変更内容が反映されるタイミングは異なります。
Integrated BrowserやLive Previewでは編集内容が自動的に反映される場合もありますが、設定によっては保存時に更新されることもあります。
表示が更新されない場合は、一度、
Ctrl + S
を押して保存してみましょう。
Macの場合は、
Command + S
です。
また、自動保存を利用したい場合は、
File
↓
Auto Save
を有効にできます。
HTMLの構文に問題がある
最小構成のHTMLで確認する
HTMLのタグ構造が大きく崩れていると、期待した表示にならないことがあります。
問題を切り分ける場合は、まず簡単なHTMLだけで表示できるか確認すると効果的です。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>表示テスト</title>
</head>
<body>
<h1>HTMLが表示されています</h1>
</body>
</html>
このコードが正常に表示される場合、VSCodeそのものではなく、元のHTMLやCSS、JavaScript側に問題がある可能性が高いと判断できます。
タグの閉じ忘れを確認する
たとえば、次のようなコードではタグ構造が崩れています。
<div>
<p>テキスト
</div>
最近のブラウザはある程度HTMLを自動補正しますが、意図しないDOM構造になる場合があります。
VSCodeのエラー表示やHTML検証機能も活用しながら確認しましょう。
CSSによって何も表示されていない
HTMLではなくCSSが原因の場合もある
プレビュー画面自体は開いているのに何も見えない場合は、CSSを確認します。
たとえば、次のCSSではページ全体が非表示になります。
body {
display: none;
}
また、
opacity: 0;
や、
visibility: hidden;
が設定されている場合も、要素が見えなくなります。
文字色と背景色が同じ場合も注意が必要です。
body {
color: white;
background: white;
}
この場合、HTMLは正常に表示されていますが、文字が背景と同化して見えません。
CSSファイルのパスが間違っている
相対パスを確認する
HTMLは表示されるものの、CSSだけが反映されない場合は、CSSファイルへのパスを確認しましょう。
たとえば、次の構成の場合、
project/
├── index.html
└── css/
└── style.css
HTML側は次のように記述できます。
<link rel="stylesheet" href="css/style.css">
一方、次の構成なら、
project/
├── css/
│ └── style.css
└── pages/
└── index.html
index.htmlから見たCSSのパスは次のようになります。
<link rel="stylesheet" href="../css/style.css">
相対パスは、HTMLファイルが存在する場所を基準に考えることが重要です。
JavaScriptファイルのパスが間違っている
script要素のsrc属性を確認する
JavaScriptが動かない場合も、ファイルパスが間違っている可能性があります。
たとえば、
project/
├── index.html
└── js/
└── main.js
なら、HTMLでは次のように指定できます。
<script src="js/main.js"></script>
ファイルパスを間違えていると、ブラウザの開発者ツールで、
404 Not Found
などが表示されることがあります。
JavaScriptエラーが発生している
Consoleを確認する
JavaScriptによってページ内容を生成している場合、JavaScriptエラーが原因で画面が空になることがあります。
たとえば、
document.getElementById("sample").textContent = "Hello";
と記述しているにもかかわらず、HTML側にid="sample"の要素が存在しない場合、getElementById()はnullを返します。
その状態で.textContentを操作するとエラーが発生します。
ブラウザの開発者ツールを開き、Consoleに、
TypeError
ReferenceError
SyntaxError
などが表示されていないか確認しましょう。
file://で開いていることが原因
ローカルサーバー経由で確認する
HTMLファイルを直接ブラウザで開くと、URLが次のようになることがあります。
file:///C:/...
HTMLやCSSだけの単純なページであれば問題ないケースも多いですが、JavaScriptで一部のWeb APIや外部ファイルを扱う場合、ブラウザのセキュリティ制限によって正常に動作しないことがあります。
たとえば、
fetch("./data.json")
のような処理です。
このような場合は、ローカルWebサーバーを利用し、
http://localhost:xxxx/
のようなURLから開くと解決する場合があります。
Live Previewなどを使えば、ローカルサーバー環境を比較的簡単に用意できます。
ReactやVueなどを通常のHTMLプレビューで開いている
フレームワークは開発サーバーを利用する
React、Vue、Next.js、Viteなどを使ったプロジェクトでは、HTMLファイルを直接プレビューする方法が適さない場合があります。
これらのプロジェクトでは、多くの場合、開発サーバーを起動して確認します。
たとえばViteを利用している場合は、
npm run dev
を実行します。
その後、ターミナルに表示された、
http://localhost:5173/
などのURLへアクセスします。
ポート番号は環境や設定によって異なる場合があります。
Next.jsでも、一般的には、
npm run dev
を実行して開発サーバーを起動します。
そのため、ReactやVueなどでプレビューできない場合は、HTMLプレビュー機能ではなく、使用しているフレームワークの開発サーバーが正常に起動しているかを確認しましょう。
拡張機能が原因になっている
不要な拡張機能を一時的に無効化する
HTMLプレビューやローカルサーバー関連の拡張機能を複数導入している場合、設定や使用ポートなどの関係で原因を特定しにくくなることがあります。
たとえば、
Live Preview
Live Server
HTML Preview系拡張機能
などです。
複数インストールしているだけで必ず競合するわけではありませんが、問題が解決しない場合は不要な拡張機能を一時的に無効化して確認するとよいでしょう。
VSCodeの一時的な不具合が発生している
ウィンドウを再読み込みする
拡張機能をインストールした直後や設定変更後に正常に動作しない場合は、VSCodeのウィンドウを再読み込みすると改善することがあります。
コマンドパレットを開き、
Ctrl + Shift + P
次のコマンドを検索します。
Developer: Reload Window
実行後に、もう一度HTMLプレビューを試してみましょう。
Remote SSHやWSLなどを利用している
ポートフォワーディングを確認する
VSCodeを次のような環境で利用している場合は、通常のローカル環境とは確認方法が異なることがあります。
Remote SSH
WSL
Dev Containers
GitHub Codespaces
たとえばRemote SSHでは、Webサーバー自体がリモートマシン上で動作している場合があります。
そのため、必要に応じてVSCodeの「Ports」機能を使い、リモート側のポートをローカルPCへ転送します。
たとえば、リモートサーバーでポート3000のWebサーバーが動いている場合でも、ポートフォワーディングを行うことでローカルブラウザからアクセスできます。
リモート環境でHTMLプレビューが表示されない場合は、HTMLだけではなく、ポート設定も確認しましょう。
vscode.devを利用している
ブラウザ版VSCodeには機能制限がある
ブラウザから利用できる、
vscode.dev
では、デスクトップ版VSCodeと同じ機能がすべて利用できるわけではありません。
拡張機能についても、Web環境に対応しているものと対応していないものがあります。
そのため、HTMLプレビューやローカルサーバー関連の機能が正常に利用できない場合は、デスクトップ版VSCodeで動作確認してみるのも一つの方法です。
HTMLプレビューが真っ白な場合の対処法
HTML・CSS・JavaScriptを順番に切り分ける
プレビュー画面は表示されるものの、中身が真っ白な場合は次の順番で確認すると原因を特定しやすくなります。
まず、HTMLファイルを保存します。
次に、body内へ直接文字を書いて表示されるか確認します。
<body>
<h1>表示テスト</h1>
</body>
これが表示される場合は、HTMLプレビューそのものは正常に動作している可能性が高くなります。
その後、
- CSSを一時的に外す
- JavaScriptを一時的に外す
- CSSやJavaScriptのファイルパスを確認する
- ブラウザのConsoleを確認する
- Networkで404エラーが出ていないか確認する
といった順番で原因を切り分けていきます。
VSCodeでHTMLプレビューが表示されないときの確認手順
基本的な項目から順番に確認する
原因が分からない場合は、次の順番で確認すると効率的です。
1. ファイル名が.htmlになっているか確認する
↓
2. VSCodeの言語モードがHTMLになっているか確認する
↓
3. HTMLファイルを保存する
↓
4. Integrated Browserで開けるか確認する
↓
5. VSCodeを最新版へ更新する
↓
6. Live Previewを利用する場合は有効になっているか確認する
↓
7. プロジェクトルートをVSCodeで開く
↓
8. 最小構成のHTMLで表示をテストする
↓
9. CSSとJavaScriptを一時的に外す
↓
10. CSS・JavaScript・画像の相対パスを確認する
↓
11. ConsoleとNetworkのエラーを確認する
↓
12. 拡張機能を一時的に無効化して確認する
↓
13. Remote SSHなどの場合はポート設定を確認する
VSCodeでHTMLプレビューが表示されない場合は原因を切り分けよう
VSCodeでHTMLプレビューが表示されない場合、必ずしもVSCode自体に問題があるとは限りません。
HTMLファイルの拡張子、言語モード、CSSやJavaScriptのパス、JavaScriptエラー、ローカルサーバー、拡張機能など、複数の原因が考えられます。
まずは最小構成のHTMLが表示できるか確認し、その後CSS、JavaScript、画像などを順番に追加していくと、原因を特定しやすくなります。
また、現在のVSCodeではIntegrated Browserを利用してHTMLを確認できます。
よりWebサーバーに近い環境で確認したい場合は、Microsoftが提供しているLive Previewを利用する方法もあります。
ReactやVue、Next.jsなどを利用している場合は、通常のHTMLプレビューではなく、それぞれの開発サーバーから確認することが重要です。
表示されないときは一度に多くの設定を変更するのではなく、HTML、CSS、JavaScript、サーバー環境を順番に切り分けながら確認すると、効率的に問題を解決できます。
以上、VSCodeでHTMLプレビューが表示されない主な原因についてでした。
最後までお読みいただき、ありがとうございました。
