はじめに (対象読者・この記事でわかること)

この記事は、VSCodeでプログラミングを始めたばかりの初心者から、日本語を含むプロジェクトで文字化けに悩んでいる中級者まで、幅広い開発者を対象にしています。 VSCodeで日本語や絵文字が文字化けする原因と、それを根本的に解決する方法を体系的に学ぶことができます。 特に、エンコーディング設定の理解、適切なフォントの選び方、プロジェクト固有の設定方法まで、実践的なノウハウをすべて網羅しています。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - VSCodeの基本的な操作（ファイルの開き方、設定画面の表示） - 文字エンコーディングの基礎知識（UTF-8やShift-JISの違いをざっくり理解） - ターミナルでの基本的なコマンド操作

VSCode文字化けのメカニズム：なぜ起こるのか

VSCodeで文字化けが発生する根本的な原因は、「ファイルの実際のエンコーディング」と「VSCodeが解釈しようとするエンコーディング」の不一致にあります。 例えば、Shift-JISで保存された古いPHPファイルをVSCodeで開いた際、デフォルト設定がUTF-8になっていると、日本語部分が文字化けして表示されます。 さらに、VSCodeは「自動エンコーディング推定」を行いますが、これが必ずしも正確ではありません。特に、日本語と英語が混在するファイルや、特殊な文字（※や☆など）を含むファイルでは、推定が外れることが多いのです。 また、文字化けには「ファイルの読み込み時」と「表示時」の2種類があります。ファイルを正しく読み込めていても、フォントが対応していなければ豆腐（□）やバツ印（�）が表示されることもあります。

実践編：文字化けを完全に抑える設定手順

ここからは、実際にVSCodeで文字化けを防ぐための具体的な設定方法を解説します。

ステップ1：グローバルなエンコーディング設定を確定させる

まず、VSCode全体のデフォルトエンコーディングを設定します。

  1. 設定画面を開き（Windows: Ctrl+,、Mac: Cmd+,）、検索ボックスにencodingと入力
  2. 「Files: Encoding」項目でUTF-8を選択（日本語環境ではこれが最も安定）
  3. 「Files: Auto Guess Encoding」は無効化（推定ミスの原因になる）

次に、settings.jsonに以下を追記して、より詳細な設定を行います：

Json

{
  "files.encoding": "utf8",
  "files.autoGuessEncoding": false,
  "files.refactoring.autoSave": "always",
  "[plaintext]": {
    "files.encoding": "utf8"
  },
  "[php]": {
    "files.encoding": "shiftjis"
  }
}

ステップ2：プロジェクト固有のエンコーディングを設定する

プロジェクトによっては、UTF-8以外のエンコーディングを使わざるを得ない場合があります。 その場合は、プロジェクトのルートディレクトリに.vscode/settings.jsonを作成し、以下のように記述します：

Json

{
  "files.encoding": "shiftjis",
  "[html]": {
    "files.encoding": "utf8"
  },
  "[css]": {
    "files.encoding": "utf8"
  }
}

これにより、そのプロジェクト内ではShift-JISがデフォルトになりながら、HTML/CSSファイルだけはUTF-8で扱われるようになります。

ステップ3：フォント設定で表示文字化けを防ぐ

エンコーディングが正しくても、フォントが日本語に対応していないと文字化けします。 おすすめの設定は以下の通りです：

Json

{
  "editor.fontFamily": "'HackGen35 Console NF', 'Noto Sans Mono CJK JP', 'monospace'",
  "editor.fontSize": 14,
  "editor.fontLigatures": true,
  "editor.unicodeHighlight.ambiguousCharacters": false,
  "editor.unicodeHighlight.invisibleCharacters": false
}

特に「HackGen35 Console NF」は、プログラミング用に最適化された日本語フォントで、イタリックやリガチャにも対応しています。

ステップ4：拡張機能で文字化けを自動検知・修正

以下の拡張機能をインストールすると、文字化けの早期発見と修正が容易になります：

  1. Japanese Language Pack for Visual Studio Code - VSCodeのUIを日本語化し、エラーメッセージも理解しやすく

  2. Encoding Helper - エンコーディングをワンクリックで切り替え可能 - 文字化け検出時に通知を出してくれる

  3. Change All End Of Line Sequence - 改行コード（CRLF/LF）も一括で統一可能

ハマった点やエラー解決

実際の現場でよくあるのが、「Gitでプルしたら文字化けした」というケースです。 これは、Gitの自動改行変換とエンコーディングの相性が悪いために起こります。

症状

  • Windows環境でShift-JISファイルを編集後、Macで開くと文字化け
  • 逆にMacでUTF-8ファイルを編集後、Windowsで開くと文字化け

解決策

プロジェクトルートに.gitattributesファイルを作成し、以下を記述：

*.php text working-tree-encoding=Shift_JIS eol=crlf
*.html text working-tree-encoding=UTF-8 eol=lf
*.css text working-tree-encoding=UTF-8 eol=lf
*.js text working-tree-encoding=UTF-8 eol=lf

これにより、Gitが自動的にエンコーディングと改行コードを管理してくれます。

まとめ

本記事では、VSCodeで発生する文字化けの原因と、それを完全に解消するための設定方法を解説しました。

  • 文字化けの根本原因は、エンコーディングの不一致とフォントの非対応
  • グローバル・プロジェクト固有・ファイルタイプごとの3段階設定が必須
  • 拡張機能と.gitattributesで、チーム開発でも文字化けをゼロに

この記事を通して、読者はVSCodeで日本語を含むプロジェクトでも、文字化けに悩まされることがなくなり、より快適なコーディング環境を手に入れられるでしょう。 次回は、VSCodeで日本語入力中の変換候補が表示されない問題の解決法について、詳しく解説する予定です。

参考資料