VSCode Dev Container設定完全ガイド｜チーム開発で環境統一する手順と実装例

チーム開発をしていて、こんな悩みはありませんか。「ローカル環境ではうまく動くのに、メンバーの環境では動かない」「環境構築に何時間も費やしてしまう」「本番環境との差分で予期しないバグが発生する」。こうした環境に関する問題は、エンジニアなら誰もが経験したことがあるはずです。

VSCode Dev Containerを使えば、こうした悩みをすべて解決できます。Docker環境をVSCode内に統合することで、チーム全員がまったく同じ開発環境を利用でき、環境依存のバグを根本的に排除できるのです。本記事では、VSCode Dev Containerの設定からチーム導入までを、実装例を交えながら手順通りに解説します。

VSCode Dev Containerとは。なぜチーム開発に必須なのか

VSCode Dev Containerは、Dockerコンテナ内で開発環境全体を構築し、VSCodeがそのコンテナに直接接続する機能です。従来のDocker開発では、ローカルでコンテナを起動してから接続するという手間がありました。一方、Dev Containerはワンクリックでそれを自動化します。

チーム開発でDev Containerが重要な理由は以下の通りです。

• メンバー全員が同じNode.js、Python、データベースのバージョンを使用する
• 環境構築時間を90%削減。新入メンバーが初日から開発に参加できる
• 本番環境とローカル開発環境の差分がほぼゼロになる
• OSの違い（MacOS、Windows、Linux）による問題が発生しない
• VSCode拡張機能もコンテナ内で動作するため、プラグインの互換性問題が消える

特に複数のマイクロサービスを扱うチームや、新入社員の教育が多い組織ほど、Dev Containerの導入効果は高いです。

おすすめ書籍・ガジェット

• Dockerの実践ガイド――Docker基礎から本番運用までカバー。Dev Container導入前に抑えておきたい知識が充実。
• Visual Studio Code実践ガイド――VSCodeの全機能を網羅。Dev Container以外の開発生産性向上テクニックも学べる。
• HHKB Professional HYBRID――エンジニア向けの最高峰キーボード。長時間の開発環境構築作業の負担を軽減。

前提条件。必要なツールのインストール

Dev Containerを使うには、以下の環境が整っている必要があります。

• Visual Studio Code（バージョン1.76.0以上）
• Docker Desktop（Windows/Mac）またはDocker Engine（Linux）
• Dev Containers拡張機能（VSCode Marketplace から無料インストール）

すべてのツールが揃っているか確認しましょう。ターミナルで以下のコマンドを実行します。

# Docker バージョン確認
docker --version

# VS Code バージョン確認
code --version

Docker Desktopがインストールされていない場合は、Docker公式サイトからダウンロードしてください。VSCode拡張機能は、VSCode左側のExtensions（拡張機能）パネルから「Dev Containers」で検索してインストールします。

ステップ1：プロジェクト直下に.devcontainerフォルダを作成

Dev Container設定は、プロジェクトルートに.devcontainerディレクトリを作成して管理します。これがチーム全員で共有される設定ファイルの保存場所となります。

# プロジェクトルートで実行
mkdir -p .devcontainer

.devcontainerフォルダの直下には、主に以下の2つのファイルを配置します。

• devcontainer.json — Dev Containerの全体設定。イメージ、ポート、環境変数などを定義
• Dockerfile — カスタムイメージの構築定義。Node.jsやPythonのバージョン、必要なツールなどを記述

後のステップで詳しく説明します。

ステップ2：devcontainer.jsonファイルを作成

devcontainer.jsonは、Dev Containerの心臓部です。このファイルにより、VSCodeとコンテナの連携方法が決まります。

以下はNode.js開発環境の例です。.devcontainer/devcontainer.jsonとして保存してください。

{
  "name": "Node.js Development Environment",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-vscode.vscode-typescript-nodejs-pack"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "[json]": {
          "editor.defaultFormatter": "esbenp.prettier-vscode"
        }
      }
    }
  },
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "remoteUser": "node",
  "postCreateCommand": "npm install && npm run build",
  "forwardPorts": [3000, 5432],
  "portsAttributes": {
    "3000": {
      "label": "Application",
      "onAutoForward": "notify"
    },
    "5432": {
      "label": "PostgreSQL",
      "onAutoForward": "ignore"
    }
  }
}

各要素の説明は以下の通りです。

• name — Dev Container の識別名。チーム内で何の環境かわかるように記述
• dockerComposeFile — Docker Compose設定ファイルのパス
• service — docker-compose.yml内で使うサービス名
• workspaceFolder — コンテナ内のプロジェクトディレクトリパス
• extensions — VSCode内で使う拡張機能。コンテナ環境にインストールされる
• postCreateCommand — コンテナ作成後に自動実行するコマンド
• forwardPorts — ホスト側にマッピングするポート番号。複数指定可能

Python開発の場合は、extensionsを以下に変更してください。

"extensions": [
  "ms-python.python",
  "ms-python.vscode-pylance",
  "ms-python.debugpy"
]

ステップ3：Dockerfileを作成して実行環境を定義

次に、.devcontainer/Dockerfileを作成します。このファイルで、Node.jsのバージョン、システムパッケージ、開発ツールなどをチーム全員が共有するバージョンに統一します。

以下はNode.js 18系とPostgresQLクライアントを含むDockerfileの例です。

FROM node:18.18-bookworm

# 必要なシステムパッケージをインストール
RUN apt-get update && apt-get install -y \
    postgresql-client \
    git \
    curl \
    build-essential \
    python3 \
    && rm -rf /var/lib/apt/lists/*

# 非rootユーザー作成（セキュリティ上のベストプラクティス）
RUN useradd -m -s /bin/bash node && \
    mkdir -p /workspace && \
    chown -R node:node /workspace

USER node
WORKDIR /workspace

# npm グローバルパッケージの設定
RUN npm config set prefix ~/.npm-global && \
    npm install -g npm@10.2.4 yarn@4.0.1

ENV PATH=/home/node/.npm-global/bin:$PATH

Python環境の場合は、FROM行を以下に変更します。

FROM python:3.11-bookworm

RUN apt-get update && apt-get install -y \
    postgresql-client \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN useradd -m -s /bin/bash python && \
    mkdir -p /workspace && \
    chown -R python:python /workspace

USER python
WORKDIR /workspace

このDockerfileを使うことで、メンバー全員がNode.js 18.18とnpm 10.2.4を使用し、環境差分による問題が発生しなくなります。

ステップ4：docker-compose.ymlでマルチコンテナ環境を構築

実務開発では、アプリケーション以外にデータベースやRedisなどが必要な場合がほとんどです。docker-compose.ymlを使えば、複数のコンテナを一度に起動・管理できます。

.devcontainer/docker-compose.ymlを以下のように作成してください。

version: '3.9'

services:

  app:

    build:

      context: ..

      dockerfile: .devcontainer/Dockerfile

    volumes:

      - ..:/workspace

      - /workspace/node_modules

    ports:

      - "3000:3000"

      - "5173:5173"

    environment:

      - NODE_ENV=development

      - DATABASE_URL=postgresql://user:password@db:5432/devdb

      - REDIS_URL=redis://redis:6379

    depends_on:

      - db

      - redis

    command: /bin/bash -c "while sleep 1000; do :; done