VSCode Dev Containers で ローカル環境を汚さない開発環境を構築する

VSCode Dev Containers で ローカル環境を汚さない開発環境を構築する手順

はじめに

この記事では、VSCode の Dev Containers 機能を使って、ローカル環境を汚さずに統一された開発環境を構築する方法を解説します。

この記事で書くこと

• 従来の開発環境が抱える課題とその解決方法
• Dev Containers の基本的な仕組みと導入メリット
• VSCode での Dev Containers のセットアップ手順
• Node.js + React アプリを使った実践例
• ポートフォワードの設定と動作確認
• 開発環境のリセット方法とトラブルシューティング

前提条件・対象読者

• Docker Desktop がインストール済み
• VSCode がインストール済み
• 開発環境のセットアップに時間をかけたくない方
• チームで統一された開発環境を実現したい方

背景・動機

開発環境の課題

従来の開発環境では、以下のような問題が頻繁に発生していました:

1. 「自分の環境では動くのに...」問題

開発者A: 「このコード、自分の環境では動くんですけど...」
開発者B: 「僕のMacだとエラーが出るんだよね」
開発者C: 「私のWindowsでも動かない...」

各開発者のローカル環境の違い(OS、ツール のバージョン、インストール済みのパッケージなど)により、同じコードでも動作が異なる問題が発生します。

2. 環境構築の複雑さ

新メンバーがプロジェクトに参加する際:

• 開発ツール のインストール
• 特定バージョンの指定
• グローバルパッケージのインストール
• データベースのセットアップ
• 環境変数の設定

これらを手順書通りに実行しても、環境差異でエラーが出ることも...

3. ローカル環境の汚染

複数のプロジェクトで異なるバージョンの Node.js や Python を使いたい場合:

• プロジェクトごとにバージョンを切り替える必要
• グローバルにインストールしたパッケージが競合
• 古いプロジェクトの依存関係が残り続ける

Dev Containers が解決すること

Dev Containers を使うと:

✅ 環境の統一: 全員が同じコンテナ環境で開発
✅ 簡単セットアップ: VSCode でフォルダを開くだけで完了
✅ ローカル環境保護: コンテナ内で完結、ホストマシンに影響なし
✅ バージョン管理: 開発環境の設定もGitで共有可能

手順・解説

1. 必要なツールの準備

Docker Desktop のインストール

まだインストールしていない場合は、公式サイトからダウンロード:

• Windows/Mac: Docker Desktop

インストール後、Docker Desktop を起動しておきます。

VSCode 拡張機能のインストール

VSCode の拡張機能マーケットプレイスから以下をインストール:

1. Dev Containers (Microsoft 公式)
   • 拡張機能 ID: ms-vscode-remote.remote-containers

検索方法:

1. VSCode を開く
2. サイドバーの拡張機能アイコンをクリック
3. 「Dev Containers」で検索
4. 「インストール」をクリック

2. プロジェクトフォルダの作成

新規プロジェクトフォルダを作成します:

mkdir my-project
cd my-project

VSCode でこのフォルダを開きます:

code .

3. Dev Container の設定追加

方法1: コマンドパレットから追加

1. コマンドパレットを開く: Ctrl/Cmd + Shift + P
2. 「Dev Containers: Add Dev Container Configuration Files...」と入力
3. 表示されるテンプレートから選択:
   • 「Node.js & TypeScript」を選択
   • Node.js のバージョンを選択(例: 20)
   • 追加機能を選択(スキップ可能)

これにより .devcontainer/devcontainer.json が自動生成されます。

方法2: AI で生成(おすすめ)

• 仕様、開発環境、運用環境をプロンプトに書いて生成する。
• 既存のプロジェクトからのコンテナ作成なら､そのプロジェクトを解析してもらって生成する。

手動で .devcontainer フォルダを作成し、devcontainer.json を作成:

.devcontainer/devcontainer.json に記述

4. Dev Container で開く

1. コマンドパレットを開く: Ctrl/Cmd + Shift + P
2. 「Dev Containers: Reopen in Container」と入力して選択
3. 初回はコンテナイメージのダウンロードとビルドが実行される(数分かかります)

画面の変化:

• VSCode の左下に緑色の表示が出て「Dev Container: Node.js Development」と表示される
• ターミナルがコンテナ内のシェルになる

5. React アプリを作成してみる

コンテナ内のターミナルで以下を実行:

# Vite で React プロジェクトを作成
npm create vite@latest my-app -- --template react-ts

# プロジェクトディレクトリに移動
cd my-app

# 依存関係をインストール
npm install

# 開発サーバーを起動
npm run dev

実行結果:

VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

6. ポートフォワードの確認

VSCode は自動的にコンテナ内のポート 5173 をホストマシンに転送します。

ポートタブで確認

1. VSCode の下部パネルで「ポート」タブをクリック
2. 転送されているポートが表示される:

   5173 -> localhost:5173
   

3. ブラウザで http://localhost:5173 にアクセス

React アプリが表示されれば成功です!

ホットリロードの確認

my-app/src/App.tsx を編集してみます:

function App() {
  return (
    <div>
      <h1>Hello Dev Containers!</h1>
      <p>ファイルを編集すると自動的に反映されます</p>
    </div>
  )
}

export default App

保存すると、ブラウザが自動的に更新されます。コンテナ内でもホットリロードが正常に動作します!

実行結果 & コツ

開発環境のリセット方法

開発中に環境がおかしくなったり、クリーンな状態に戻したい場合:

方法1: コンテナの再構築

1. コマンドパレット: Ctrl/Cmd + Shift + P
2. 「Dev Containers: Rebuild Container」を選択
3. コンテナが削除され、新しくビルドされる

方法2: 完全にクリーンアップ

# コンテナを停止
docker stop <container_id>

# コンテナを削除
docker rm <container_id>

# イメージも削除したい場合
docker rmi <image_id>

その後、VSCode で「Reopen in Container」を実行すれば新しい環境が構築されます。

つまずきポイントと回避策

1. Docker Desktop が起動していない

症状: 「Cannot connect to the Docker daemon」エラー

解決策:

• Docker Desktop を起動する
• タスクトレイ(Windows)またはメニューバー(Mac)でDockerアイコンを確認
• Docker が完全に起動するまで待つ(数十秒かかる場合あり)

2. コンテナビルドが遅い・失敗する

症状: イメージダウンロードに時間がかかる、またはタイムアウト

解決策:

// devcontainer.json に追加
{
  "build": {
    "dockerfile": "Dockerfile",
    "args": {
      "HTTP_PROXY": "your-proxy:port"  // プロキシ環境の場合
    }
  }
}

または、事前にイメージをダウンロード:

docker pull mcr.microsoft.com/devcontainers/typescript-node:20

3. ファイル変更がコンテナに反映されない

症状: ホストでファイルを編集してもコンテナ内で変更されない

原因: ボリュームマウントの問題

解決策:

// devcontainer.json
{
  "workspaceFolder": "/workspace",
  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind"
}

4. 拡張機能がインストールされない

症状: devcontainer.json で指定した拡張機能が動作しない

解決策:

1. コンテナを再構築: 「Rebuild Container」
2. 拡張機能 ID を確認(VSCode の拡張機能ページで確認)
3. ネットワーク環境を確認(プロキシの設定など)

5. ポートフォワードが機能しない

症状: localhost:3000 にアクセスできない

解決策:

1. VSCode の「ポート」タブで転送状態を確認
2. 手動でポートを追加:
   • 「ポート」タブの「+」アイコンをクリック
   • ポート番号を入力(例: 3000)
3. devcontainer.json の forwardPorts を確認

"forwardPorts": [3000, 5173]

開発のコツ

1. チーム全員で同じ環境を共有

.devcontainer フォルダを Git にコミット:

チームメンバーは:

1. リポジトリをクローン
2. VSCode で開く
3. 「Reopen in Container」を選択

これだけで同じ環境で開発開始!

2. 複数のプロジェクトで使い回す

よく使う設定は別プロジェクトにもコピー:

# テンプレートとして保存
cp -r .devcontainer ~/devcontainer-templates/nodejs-typescript/

# 新プロジェクトで使用
cp -r ~/devcontainer-templates/nodejs-typescript/.devcontainer ./

3. 起動時のスクリプト自動化

postCreateCommand で依存関係を自動インストール:

{
  "postCreateCommand": "npm install && npm run setup"
}

まとめ(気づき)

学んだこと

1. 環境統一の威力: 「私の環境では...」問題の解消
2. セットアップの簡単さ: 新メンバーも数分で開発開始可能
3. ローカル環境保護: ホストマシンに一切影響なし
4. 設定の共有: .devcontainer を Git 管理することでチーム全体で統一
5. VSCode 統合の便利さ: 拡張機能も設定もコンテナに含められる

Dev Containers のメリット

• ✅ プロジェクトごとの完全分離: Node, Python などのバージョン違い のプロジェクトを同時進行
• ✅ 即座にリセット可能: 環境が壊れても数分で復旧
• ✅ ドキュメント不要: コードと設定だけで環境が再現できる
• ✅ オンボーディング時間削減: 新メンバーの環境構築が劇的に早くなる

ハマりやすいポイント

• Docker Desktop の起動: 意外と忘れがち、常駐させておくと便利
• 初回ビルド時間: 5-10分かかることもあるので気長に待つ
• ポート転送: 自動で転送されるが、「ポート」タブで確認する癖をつける

次に伸ばすべきポイント

• Docker Compose との連携: 複数サービス(DB など)の統合
• カスタム Dockerfile: より細かい環境設定
• Features の活用: Git、GitHub CLI などの追加ツール
• デバッグ設定: コンテナ内でのデバッグ環境構築
• CI/CD 連携: GitHub Actions で同じコンテナを使う

実務での活用シーン

この Dev Containers は以下のような場面で特に有効です:

1. 新規プロジェクトの立ち上げ: 環境構築に時間をかけない
2. チーム開発: 全員が同じ環境で作業
3. 複数プロジェクトの並行作業: バージョン違いも工夫次第
4. オープンソース: すぐに開発環境が整う
5. 技術検証・学習: 気軽に試して、気軽に壊し、削除

Dev Containers が VSCode の拡張機能のため、VSCode 限定。