VSCodeでDockerコンテナ内デバッグを始める完全ガイド

前提条件と必要なツール

このセクションでは、開発環境を構築する前に準備すべきソフトウェアと、そのインストール・バージョン確認方法を紹介します。ツールが正しくインストールされていないと、コンテナ起動や拡張機能の認識に失敗しやすくなるため、必ずここまでに作業を完了させてください。

Docker のインストール（Windows / macOS）

Docker は公式サイトから 最新安定版 を取得するだけで利用できます。インストーラは OS に合わせたパッケージが自動的に選択されますので、バージョン番号を固定せず「最新版」を入手してください。

必要条件と確認ポイント

• OS の対応：Windows 10/11（Pro 以降）・macOS 12.0 以上。
• 仮想化支援機能：BIOS/UEFI で VT‑x または AMD‑V が有効になっていることを確認します。

インストール後、ターミナル（PowerShell / Bash）で次のコマンドを実行し、Docker Engine と Docker CLI が利用可能か確かめます。

ポイント：docker version だけでなく docker info も併せて実行すると、リソース割当やストレージ設定の概要が確認できます。

Linux 環境向け Docker Engine のインストール

Linux では Docker Desktop が提供されないため、Docker Engine（Community Edition） を直接インストールします。以下は Ubuntu/Debian 系と RHEL/CentOS 系の代表的な手順です。別ディストリビューションを使用する場合は公式ドキュメント（Docker Engine install guide）をご参照ください。

1. パッケージ情報の取得と前提パッケージのインストール

2. Docker の公式 GPG 鍵とリポジトリを追加

3. Docker Engine のインストールと起動

4. インストール確認

注意：Linux 環境では docker グループへ自分のユーザーを追加すると、sudo なしで Docker コマンドが使えるようになります。
bash
sudo usermod -aG docker $USER && newgrp docker

VSCode と推奨拡張機能の導入

VSCode 本体は公式サイトから 最新安定版 を取得し、インストール後に以下の拡張機能を追加します。バージョン番号は「最新版」かつ「拡張機能一覧で表示されるもの」で確認してください。

バージョン確認コマンド

出力例は 0.315.x、1.28.x のように「x」以下が更新されるたびに変わりますので、公式 Marketplace に表示された最新版と照らし合わせてください。

まとめ：Windows/macOS では Docker Desktop、Linux では Docker Engine をそれぞれ最新の安定版で導入し、VSCode と必須拡張機能を揃えることで、以降の手順がスムーズに進みます。

Dev Container の基本概念と設定ファイル

この章では、Dev Containers（Remote Containers） がどのように VSCode と Docker を橋渡しするかを解説し、最小構成の devcontainer.json の書き方を実例で示します。設定はシンプルに保ちつつ、後から機能拡張できる形にしておくと運用が楽になります。

Dev Container の仕組み

Dev Container は「コード + 開発環境 = コンテナイメージ」という考え方です。VSCode が devcontainer.json を読み取り、指定されたベースイメージや Dockerfile からコンテナを自動ビルドし、内部に VSCode Server（拡張機能が走るプロセス）を起動します。その結果、ローカルと同様の UI でリモート環境にアクセスでき、チーム全員が統一された依存関係を共有できます。

devcontainer.json の主要キー

以下は代表的なキーと簡単な説明です。各項目は必須ではありませんが、プロジェクトの要件に合わせて選択します。

最小構成例（Python プロジェクト）

このファイルをプロジェクトルートの .devcontainer/devcontainer.json に配置し、VSCode の Open in Container を実行すると自動でビルド・接続が開始されます。

ポイント：features を利用すれば debugpy や node などデバッグツールを手軽にインストールでき、後述の launch.json とシームレスに連携します。

VSCode からコンテナへリモート接続する手順

ここでは「Remote Containers: Open Folder in Container」コマンドを使ってプロジェクトをコンテナ化し、VSCode が自動的に接続する流れを示します。OS に依存せず同一の操作で完了できる点が利便性の鍵です。

手順概要

1. VSCode で対象フォルダーを開く（.devcontainer ディレクトリが存在することを確認）。
2. Ctrl+Shift+P でコマンドパレットを開き、Remote-Containers: Open Folder in Container を選択。
3. VSCode が内部で次の処理を実行します
4. devcontainer.json の情報から Docker イメージをビルドまたはプル
5. 必要なボリュームマウントやポート公開オプションを付与してコンテナ起動
6. コンテナ内部に VSCode Server を起動し、ローカル UI と自動的に切り替える

ビルドログはステータスバーの Dev Container アイコンから確認でき、エラーが出た場合は「Docker リソース割当」や「ファイル共有設定」を見直すだけで多くは解決します。

ヒント：devcontainer.json に runArgs でポート公開 (-p) を明示すると、デバッグ時のポート衝突を防ぎやすくなります。

コンテナ内デバッグ設定（launch.json とアタッチ方式）

本章では、attach デバッグ の概念と具体的な launch.json 設定例を言語別に示します。アタッチ方式はコンテナ内部で既に起動しているデバッガーへ VSCode が接続するため、ビルドや再起動の待ち時間が最小化されます。

Python（debugpy）での attach 手順

以下の流れは公式 VSCode ドキュメントと同等の手順です。外部リンクに依存せず、実装コードだけを示しています。

1. コンテナ側に debugpy をインストール
   dockerfile
RUN pip install --no-cache-dir debugpy

2. アプリ起動スクリプトにデバッグ待機ロジックを追加（環境変数 DEBUG が設定されているときだけ有効）

python
import os, sys, debugpy

if os.getenv("DEBUG"):
debugpy.listen(("0.0.0.0", 5678))
print("[debugpy] Waiting for debugger attach on port 5678...")
debugpy.wait_for_client()
# 本来のエントリーポイント


1. devcontainer.json に環境変数とポート公開を追記

json
"runArgs": [
"-e", "DEBUG=1",
"-p", "5678:5678"
]

1. VSCode の launch.json に attach 設定を追加

json
{
"version": "0.2.0",
"configurations": [
{
"type": "python",
"request": "attach",
"name": "Docker: Python Attach",
"connect": {
"host": "localhost",
"port": 5678
},
"pathMappings": [
{
"/workspace": "${workspaceFolder}"
}
]
}
]
}

この構成でデバッグを開始すると、VSCode が debugpy の待ち受けポートに接続し、ブレークポイントが有効になります。

Node.js（--inspect）での attach 手順

1. Dockerfile に Node.js と必須ツールをインストール（公式イメージ利用可）。
2. package.json のスクリプトに --inspect=0.0.0.0:9229 を追加

json
"scripts": {
"dev:debug": "node --inspect=0.0.0.0:9229 index.js"
}

1. devcontainer.json でポート公開と環境変数を設定

json
"runArgs": ["-p", "9229:9229"]

1. VSCode の launch.json（Node 用）

json
{
"type": "pwa-node",
"request": "attach",
"name": "Docker: Node Attach",
"port": 9229,
"address": "localhost",
"localRoot": "${workspaceFolder}",
"remoteRoot": "/workspace"
}

他言語の一般的な attach パターン

いずれの場合も「コンテナ内でデバッガーを待ち受けさせ、外部ポートを公開」することが共通要件です。pathMappings（または localRoot/remoteRoot）でローカルとコンテナのパス対応を正しく設定すれば、ブレークポイントが期待どおりにヒットします。

共通トラブルシューティングとプラットフォーム別注意点

デバッグ環境構築時に頻出する問題とその対処法をまとめました。OS ごとの設定差異にも触れているので、該当箇所だけ参照してください。

ポートフォワーディングが機能しない場合

• 原因：docker run の -p オプションが不足、または Docker Desktop / Engine のファイアウォール設定でブロックされている。
• 確認手順

bash
docker ps --format "table {{.Names}}\t{{.Ports}}"

表示に 0.0.0.0:5678->5678/tcp が無い場合はポートが公開されていません。
- 解決策：devcontainer.json の runArgs に ["-p","5678:5678"] を追記し、Docker Desktop（Settings → Resources → Network）で「Allow incoming connections」設定を有効化します。

コンテナ再起動時にデバッガーが切断される

• 原因：VSCode の自動再接続機能が無効。
• 対策：ユーザー設定 settings.json に以下を追加します。

json
{
"debug.node.autoAttach": "on",
"remote.containers.autoAttachOnFolderOpen": true,
"docker.debugger.attach.autoReconnect": true // VSCode 1.85+ のオプション例
}

再起動後はコンテナが作り直されてもデバッガーが自動で再接続します。

権限エラー・ファイル共有設定

OS 別リソース割当と推奨設定

• Windows (WSL2 バックエンド)：CPU 2 コア以上、メモリ 4 GB 以上を確保。
• macOS（Intel / Apple Silicon）：CPU 2 コア、メモリ 4 GB 推奨。M1/M2 の場合は docker buildx が自動で ARM イメージを生成しますが、一部パッケージのビルドに時間がかかることがあります。
• Linux：/etc/docker/daemon.json でデフォルトリソース制限（例："default-runtime": "runc"）を設定し、必要に応じて --cpus・--memory オプションを runArgs に追加。

公式ドキュメントの要点まとめ

• VSCode Docs – Debugging in Containers
• docker.debugger.attach の自動生成ロジックと preLaunchTask を使った Compose 起動例。
• Docker Official Docs – Best practices for container debugging
• ポート公開、ユーザー権限、ログ取得のベストプラクティスが掲載されています。

上記公式ページは随時更新されるため、作業前に最新情報を確認してください（リンクは https://code.visualstudio.com/docs/containers/debugging と https://docs.docker.com/config/containers/container-debugging/）。

まとめ

1. ツールの最新版を導入
2. Windows/macOS は Docker Desktop、Linux は Docker Engine の最新安定版。

3. VSCode と必須拡張機能（Dev Containers・Docker）も公式 Marketplace の「最新」バージョンで揃える。

4. devcontainer.json で環境をコード化

5. ベースイメージ、必要な features、ポート公開・環境変数などを明示的に記述し、リポジトリに含めてチーム全体で共有。

6. VSCode の「Open in Container」で自動構築

7. 手順は OS 非依存で統一でき、ビルドログやエラーは VSCode UI から簡単に確認可能。

8. attach デバッグを活用した高速なブレークポイント

9. Python（debugpy）・Node.js（--inspect）など言語別サンプルを参考に、launch.json と devcontainer.json の連携を設定すれば、ほぼ即座にデバッガーへ接続できる。

10. 典型的な障害は公式ドキュメントと本チェックリストで解決

11. ポートフォワーディング、再起動時の自動再接続、ファイル共有権限などは設定項目を見直すだけで多くが対処できる。

これらの手順通りに環境構築すれば、ローカルマシンに余計な依存関係を持たせず、チーム全体で統一されたコンテナ内デバッグ環境を迅速に提供できます。ぜひ本ガイドをプロジェクトの「セットアップ手順」ドキュメントとして保存し、継続的に活用してください。