【よくあるトラブル対策】VSCodeで起こりやすいエラーとその解決方法まとめ

こんにちは！プログラミング知識ゼロから、AIの力を借りて独学でWebサイトを立ち上げた者です。皆さんの「わからない」が、手に取るようにわかります。なぜなら、ほんの数ヶ月前まで、私も皆さんと同じ場所で頭を抱えていたからです。

特にVSCode（Visual Studio Code）を使い始めたばかりの頃は、次から次へと現れるエラーメッセージに、心が折れそうになりますよね。「ただコードを書きたいだけなのに…！」と。

この記事では、そんな私が実際に遭遇して乗り越えてきた、VSCodeで本当によくあるエラーとその解決策を、どこよりも分かりやすく、専門用語を避けて解説します。目的はただ一つ、皆さんに「動く！」という成功体験をしてもらうことです。この記事を読めば、もうエラーは怖くありません。一つずつ、一緒に解決していきましょう！

【超基本】まず試すべき！トラブルシューティングの三種の神器

具体的なエラーの話に入る前に、どんな問題が起きてもまず試してほしい「基本のき」があります。驚くほど多くの問題が、これで解決してしまうんですよ。

1. とにもかくにも「再起動」

信じられないかもしれませんが、これが一番効果的です。「何かおかしいな？」と思ったら、まずはVSCodeを完全に終了して、もう一度立ち上げ直してみてください。拡張機能の読み込みに失敗していたり、一時的な不具合だったりする場合、これだけであっさり直ることが本当に多いんです。パソコンの調子が悪い時に再起動するのと同じですね。

2. 拡張機能を一旦すべてオフにする

VSCodeが便利なのは、便利な「拡張機能」のおかげです。しかし、この拡張機能同士がケンカをして、予期せぬエラーを引き起こすことがあります。

原因が拡張機能にあるか確かめるには、「拡張機能ビスケット」という機能が便利です。

コマンドパレットを開きます (mac: Cmd + Shift + P, Win: Ctrl + Shift + P)。
>拡張機能ビスケット または >Extensions: Bisect と入力し、実行します。
画面の指示に従って操作すると、VSCodeが自動で拡張機能を半分ずつ無効化していき、問題の原因となっている拡張機能を特定してくれます。

これで問題が解決した場合、原因は拡張機能のどれかです。原因の拡張機能がわかったら、それを無効化するか、設定を見直しましょう。

3. 問題を切り分ける

「いつから」「何をしたら」このエラーが出るようになったのか、思い出してみましょう。

新しい拡張機能を入れた直後から？
特定のファイルを開いた時だけ？
HTMLファイルでは大丈夫だけど、JavaScriptファイルだとエラーが出る？

このように、問題が起こる条件を特定できると、解決への近道になります。

【シーン別】私が泣いた…よくあるエラーとコピペで動く解決策

ここからは、私がWebサイト制作中に実際に遭遇し、解決に時間がかかった具体的なエラーをご紹介します。きっと、あなたの画面に出ているエラーもあるはずです。

Case 1：日本語が謎の記号に！「文字化け」エラー

HTMLファイルに日本語を書いたはずが、ブラウザで表示するとや縺ゅ＞縺のような謎の記号になってしまう…。これは初心者が必ず通る道と言ってもいい「文字化け」です。

原因:
これは、ファイルが保存されている「文字コード（エンコーディング）」と、ブラウザが「この文字コードで書かれているだろう」と解釈する文字コードが食い違っていることが原因です。日本では昔、Shift_JISという形式がよく使われていましたが、現在は世界標準のUTF-8を使うのが一般的です。

解決策：
VSCodeの設定を、今後作るファイルもすべてUTF-8で保存するように変更してしまいましょう。一度設定すれば、もう文字化けで悩むことはありません。

macなら Cmd + , (カンマ)、Windowsなら Ctrl + , (カンマ) で設定画面を開き、右上のファイルアイコンをクリックしてsettings.jsonを開いて、以下のコードをコピペしてください。

{
  // ファイル関連の設定
  "files.encoding": "utf8", // ファイルを開くときのデフォルトの文字コードをUTF-8に
  "files.autoGuessEncoding": true, // ファイルを開くときに文字コードを自動で推測する
  "files.eol": "\n" // ファイルの改行コードをLF(\n)に統一する
}

すでに{}の中に何か書かれている場合は、中の設定項目（"files.encoding": "utf8",など）だけを追記してくださいね。

Case 2：コマンドが効かない！「command not found」エラー

Web開発では、VSCodeに内蔵されている「ターミナル」でnpmやgitといったコマンドをよく使います。しかし、いざコマンドを打ってもzsh: command not found: npmのように「そんなコマンド知りません」と怒られてしまうことがあります。

原因:
これは、パソコンにそのコマンド（プログラム）がインストールされていなかったり、インストールはされているものの、パソコンが「そのコマンドがどこにあるのか」を知らなかったりする（= PATHが通っていない）ことが原因です。

解決策：
まずは、本当にインストールされているか確認しましょう。例えば、Node.js（npmコマンドを含みます）なら、ターミナルで以下のコマンドを打ってみてください。

node -v

バージョン番号（例: v20.11.0）が表示されればインストールされています。もしcommand not foundと出たら、そもそもインストールができていません。Node.js公式サイトからインストールしましょう。

インストールされているのにエラーが出る場合は、VSCodeを一度再起動してみてください。インストール直後は、VSCodeが新しいPATHを認識できていないことがあります。

Case 3：コードが綺麗にならない！ Prettier / ESLint が動かない

ファイルを保存した瞬間に、ぐちゃぐちゃのコードが魔法のように整形される…。これを実現してくれるのがPrettierやESLintといったフォーマッター/リンターです。でも、設定したはずなのに全然動いてくれない！というのも、よくある悩みです。

原因:
考えられる原因はいくつかあります。
1. VSCodeのPrettierやESLint拡張機能がインストールされていない、または無効になっている。
2. プロジェクトに設定ファイル (.prettierrc, .eslintrc.js) がない。
3. VSCodeの設定で「保存時にフォーマットする」が有効になっていない。
4. 複数のフォーマッターが競合している。

解決策：
以下の設定を、先ほども登場したsettings.jsonにコピペしてみてください。これは、あらゆる問題を解決してくれる「全部入り」の設定です。私がWebサイトを作ったときも、この設定に何度も助けられました。

{
  // ----- フォーマットとリンターに関する設定 -----

  // デフォルトのフォーマッターをPrettierに設定
  // これで他のフォーマッターとのケンカを防ぎます
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // ファイル保存時に自動でフォーマットを実行する
  "editor.formatOnSave": true,

  // ESLintにもコードをチェック＆修正してほしいファイルの種類を指定
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // ファイル保存時にESLintによる自動修正も実行する
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

【ポイント解説】
特に重要なのが"editor.defaultFormatter": "esbenp.prettier-vscode"です。VSCodeは素の状態でもコードを整形する機能を持っています。そのため、Prettier拡張機能を入れると、「どっちの言うことを聞けばいいの？」と混乱してしまうことがあるのです。この一行で「整形のことなら、何でもPrettier先生に任せます！」と宣言することで、競合を防ぐことができます。

もちろん、PrettierとESLintの拡張機能がインストールされていることが大前提ですよ！

Case 4：インポートが見つからない！「Cannot find module」エラー

JavaScriptやTypeScriptで開発していると、importを使って他のファイルから部品（モジュール）を読み込みますよね。その際にCannot find module './components/Button'のようなエラーが出ることがあります。

原因:
これは単純なパスの指定ミスがほとんどです。しかし、プロジェクトが複雑になってくると、../../../../utils/helper.jsのように、相対パスの../がどんどん深くなってしまい、間違いやすくなります（私はこれを「("../") 地獄」と呼んでいます）。

解決策：
この「("../") 地獄」から抜け出すために、jsconfig.json（TypeScriptの場合はtsconfig.json）という設定ファイルを作りましょう。これは、VSCodeに「プロジェクトの基準となる場所（ルート）はここだよ」と教えてあげるためのファイルです。

プロジェクトのトップ（package.jsonがあるのと同じ階層）にjsconfig.jsonという名前のファイルを作成し、以下の内容をコピペしてください。

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "exclude": ["node_modules"]
}

【ポイント解説】
この設定をすると何が嬉しいか。例えば、src/components/ui/Button.jsxというファイルを、全く違う階層にあるsrc/pages/index.jsから読み込みたいとします。

設定前：import Button from '../../components/ui/Button'; （階層を間違えやすい…）
設定後：import Button from '@/components/ui/Button'; （@がsrcフォルダを指すので、いつでも同じように書ける！）

これで、ファイルの場所を移動しても、import文を修正する必要がほとんどなくなります。これは本当に革命的ですよ！

【応用編】もう怖くない！エラーが出たらAIにこう聞こう！

私が独学でWebサイトを作れたのは、間違いなくAIアシスタントのおかげです。エラーメッセージが出ても、パニックになる必要はありません。それは、AIに質問するための最高の「材料」なんです。

でも、ただエラーメッセージをコピペするだけでは、良い回答が得られないこともあります。良い答えを引き出すには、聞き方にコツがあるんです。

最強の質問テンプレート

エラーに遭遇したら、以下のテンプレートを使ってAIに質問してみてください。

件名: [使用技術]で[エラー内容]が発生しました

1. 背景・目的:
（例: Next.jsとTypeScriptを使って、コンポーネントをインポートしようとしています。）

2. 発生している問題:
（例: npm run devを実行すると、ターミナルに以下のエラーメッセージが表示されます。）

ここにエラーメッセージをそのまま貼り付ける

3. 該当のコード:
（例: エラーが出ているファイルの、関連する部分のコードです。）

ここにコードを貼り付ける

4. 試したこと:
（例: npm installの再実行、VSCodeの再起動は試しましたが、解決しませんでした。）

5. 質問:
このエラーの根本的な原因と、解決するための具体的な手順を教えてください。

このように、「何をしようとして」「何が起きて」「何を試したか」をセットで伝えることで、AIは状況を正確に理解し、的確な解決策を提示してくれます。エラーログは、最高のヒントの宝庫です。ぜひ、AIを最強の相棒にしてください。

まとめ

今回は、VSCodeで初心者がつまずきやすいエラーと、その具体的な解決策について、私の実体験を交えながら解説しました。

エラーは、プログラミングを学ぶ上では避けて通れないものです。でも、一つ一つのエラーには必ず原因があり、解決する方法があります。エラーメッセージは敵ではなく、あなたに「ここが違うよ！」と教えてくれる親切なサインなんです。

この記事が、あなたの「わからない」を「わかった！」に変える手助けになれば、これほど嬉しいことはありません。エラーを乗り越えるたびに、あなたは確実にレベルアップしています。自信を持って、コーディングを楽しんでくださいね！