「Macでは動くのに」を完全撲滅。VS Code Dev Containersで手元PCを汚さず開発環境を揃える実践ガイド

2026/08/25

開閉

新しいプロジェクトに参画した初日、「社内Wikiのセットアップ手順書を読んで環境を作っておいてね」と言われたものの、1行目の npm install や bundle install からエラーの洗礼を受け、気づけば丸一日溶けていた……。

エンジニアとしてキャリアを重ねる中で、私自身も数え切れないほどこの「環境構築の洗礼」を浴びてきましたし、逆に自分がメンターとして後輩を迎えた際にも、相手のPCのOS差分や古いNode.jsのバージョン干渉でトラブル対応に追われることが多々ありました。

こうした「私のPCでは動くんですけど問題」を根本から解決してくれたのが、VS Codeの公式拡張機能 Dev Containers （旧 Remote - Containers）です。

今回は、ローカルマシンに言語ランタイムやミドルウェアを一切インストールせず、手元のPCをクリーンに保ちながら、チーム全員がOSの差分に煩わされずに開発をスタートできる実践的なセットアップ手順をご紹介します。

Dev Containers が開発スタイルを変える理由

従来のDocker開発では、「ローカルでソースコードを編集し、ターミナルから docker compose exec でコマンドを実行する」というスタイルが一般的でした。しかし、この方法ではVS CodeのIntelliSense（コード補完）やデバッガがコンテナ内部のライブラリを直接認識できず、手元のエディタ上では未解決エラー（赤波線）が出るといったストレスがありました。

Dev Containers を導入すると、コンテナ内部で軽量な「VS Code Server」が起動し、手元のVS Code UIと通信する仕組みをとります。そのため、「ローカルPCにはDockerとVS Codeしか入っていない状態」であっても、コンテナ内のライブラリを直接参照した強力な補完やステップ実行デバッグを活用できます。

なお、この .devcontainer の仕様はMicrosoft単独のものではなく、Development Containers Specification としてオープンな標準規格として策定が進められており、GitHub Codespacesなどでも共通の設定としてそのまま活用できます。

ローカル開発環境と Dev Containers の比較

graph TD
    subgraph "従来の環境 (ローカル依存)"
        A1["Host PC OS"] --> B1["Node v16 / Python 3.8 直接インストール"]
        B1 --> C1["VS Code (ローカルライブラリを参照)"]
        C1 --> D1["バージョン衝突・OS差分エラー発生"]
    end
    
    subgraph "Dev Containers 環境 (完全隔離)"
        A2["Host PC OS (Dockerのみ)"] --> B2["Docker Container (.devcontainer)"]
        B2 --> C2["指定 Node v20 / Python 3.11 完備"]
        C2 --> D2["VS Code Server がコンテナ内で直に動作"]
        D2 --> E2["100% 同じ環境を誰でも即座に再現"]
    end

動作確認環境

本記事で解説する手順および設定例は、以下の環境で検証を行っています。

ホストOS: macOS Sonoma 14.5 / Windows 11 Pro (23H2)
コンテナランタイム: Docker Desktop 4.30+ (Docker Engine 26.1) ※WindowsはWSL2バックエンド
エディタ: Visual Studio Code 1.90+
拡張機能: Dev Containers (ms-vscode-remote.remote-containers) v0.380+

`.devcontainer` 設定ファイルの作成ステップ

プロジェクトのルートディレクトリに .devcontainer/ ディレクトリを作成し、以下の2つのファイルを配置します。

.devcontainer/devcontainer.json （設定ファイル）
.devcontainer/Dockerfile （または docker-compose.yml）

1. `devcontainer.json` の記述例

Python 3.11 環境を例に、チーム推奨の拡張機能（BlackやFlake8等）や保存時フォーマットを自動適用させる設定例です。設定項目の全仕様は devcontainer.json 公式リファレンスで確認できます。

{
  "name": "Python 3.11 Development Environment",
  "build": {
    "dockerfile": "Dockerfile"
  },
  // VS Codeの設定をコンテナ内へ自動適用
  "customizations": {
    "vscode": {
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python",
        "editor.formatOnSave": true,
        "python.formatting.provider": "none",
        "[python]": {
          "editor.defaultFormatter": "ms-python.black-formatter"
        }
      },
      // チームで統一したい推奨拡張機能を自動インストール
      "extensions": [
        "ms-python.python",
        "ms-python.black-formatter",
        "njpwerner.autodocstring",
        "eamodio.gitlens"
      ]
    }
  },
  // ポートフォワーディングの設定
  "forwardPorts": [8000],
  // コンテナ作成後に自動実行するコマンド
  "postCreateCommand": "pip install --upgrade pip && pip install -r requirements.txt",
  // リモートユーザーの指定
  "remoteUser": "vscode"
}

2. `Dockerfile` の記述例

ベースイメージには、公式の Microsoft Dev Containers Images を使用するのがおすすめです。一般のDockerイメージと異なり、開発に必要な非rootユーザー（vscode）やGit、sudo権限があらかじめ整備されているため、最小限の記述で安定して動作します。

FROM mcr.microsoft.com/devcontainers/python:1-3.11-bullseye

# 必要な追加パッケージのインストール
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install --no-install-recommends postgresql-client curl \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

コンテナの起動と実機検証ログ

設定ファイルを配置したら、実際にコンテナ環境を起動して動作を検証します。

VS Codeで拡張機能「Dev Containers」 (ms-vscode-remote.remote-containers) をインストール。
コマンドパレット（Ctrl + Shift + P または Cmd + Shift + P）を開き、Dev Containers: Reopen in Container を選択。
初回はDockerイメージのビルドと postCreateCommand による依存パッケージのインストールが自動実行されます。

コンテナのビルドと接続が完了すると、ウィンドウ左下のステータスバーに Dev Container: Python 3.11 Development Environment と表示されます。

ここでVS Codeの統合ターミナル（`Ctrl + ``）を開くと、ホストOSではなくコンテナ内部のシェルが直接立ち上がっていることが確認できます。

# コンテナ内のユーザー・OS情報の確認
$ whoami
vscode

$ uname -a
Linux 1a2b3c4d5e6f 6.6.137+ #1 SMP PREEMPT_DYNAMIC Linux

# 指定したPythonランタイムとパスの確認
$ which python
/usr/local/bin/python

$ python --version
Python 3.11.9

# postCreateCommandで導入されたパッケージの確認
$ pip list | grep -E "(black|flake8|requests)"
black             24.4.2
flake8            7.0.0
requests          2.31.0

手元のホストPC側にはPythonを一切インストールしていなくても、VS Code内ではBlackによる保存時自動フォーマットや型ヒントの補完がすべて問題なく動作します。

現場で遭遇しやすいOS差異と2大トラブル対策

Dev Containersは非常に便利ですが、実務でMacユーザーとWindowsユーザーが混在するチームへ導入する際には、特有の落とし穴が存在します。私自身が現場で実際に遭遇し、対応した2つのポイントを紹介します。

1. Windows環境での改行コード（CRLF）による起動エラー

Windows環境でGitリポジトリをクローンすると、Gitのデフォルト設定（core.autocrlf = true）によってシェルスクリプトや設定ファイルの改行コードが CRLF に自動変換されてしまうことがあります。

この状態でコンテナを起動すると、Linuxコンテナ内のbashが \r を認識できず、以下のようなエラーを出してコンテナ作成や postCreateCommand が停止します。

/bin/bash: ./setup.sh: /bin/bash^M: bad interpreter: No such file or directory

この問題を防ぐには、リポジトリのルートに .gitattributes を配置し、スクリプト類やDev Container設定の改行コードを LF に固定しておくのが実務上の定石です。

# .gitattributes
* text=auto eol=lf
*.sh text eol=lf
.devcontainer/** text eol=lf

2. Windows（WSL2）におけるファイルI/Oパフォーマンスの低下

Windows上でDocker Desktopを使う場合、リポジトリのクローン先ディレクトリに注意が必要です。

WindowsのCドライブ直下（/mnt/c/Users/...）にリポジトリを置き、それをコンテナにマウントすると、WindowsのNTFSとLinux（WSL2/コンテナ）をまたぐファイルアクセスが発生し、npm install やファイル監視（Hot Reload）が極端に低速になります。

Windows環境では、リポジトリを必ずWSL2の内部ファイルシステム (\\wsl$\Ubuntu\home\<ユーザー名>\...) 側にクローンし、VS Codeの「WSL拡張機能」経由で開いたうえで Reopen in Container を実行してください。これだけでファイルI/O速度が数倍から十数倍改善します。