Konfiguracja kontenerów deweloperskich

Nowy programista dołącza do Twojego zespołu. Spędza dwa dni na konfigurowaniu swojego środowiska: instaluje Node.js, konfiguruje PostgreSQL, walczy z menedżerami wersji Pythona, a następnie odkrywa, że Claude Code potrzebuje określonych zmiennych środowiskowych do pracy z Twoim proxy. Kontenery deweloperskie eliminują to w całości — każdy programista otrzymuje identyczne, wstępnie skonfigurowane środowisko z gotowym do działania Claude Code.

Co wyniesiesz z tego rozdziału

Gotową do produkcji konfigurację devcontainer z wstępnie zainstalowanym Claude Code
Konfigurację GitHub Codespaces dla dostępu do Claude Code przez przeglądarkę
Wzorce współdzielenia konfiguracji Claude Code w środowiskach kontenerowych
Zagadnienia bezpieczeństwa związane z uruchamianiem Claude Code w kontenerach

Podstawowa konfiguracja kontenera deweloperskiego

Plik devcontainer.json

Utwórz .devcontainer/devcontainer.json w swoim repozytorium:

{
  "name": "Project Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {},
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "postCreateCommand": "npm install && npm run build",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest",
  "forwardPorts": [3000, 5432],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "remoteEnv": {
    "NODE_ENV": "development"
  }
}

Gotowy devcontainer.json dla projektu TypeScript z Claude Code:

{
  "name": "TS + Claude Code",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest && npm install",
  "forwardPorts": [3000],
  "remoteEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
  ]
}

Wpis mounts udostępnia Twoją lokalną konfigurację Claude Code (sesje, ustawienia, pamięć) kontenerowi.

Kopiuj-wklej prompt, aby Claude Code wygenerował dla Ciebie devcontainer:

Generate a .devcontainer/devcontainer.json for this repo. Detect the package manager and language runtime version from the lockfile and package.json (or equivalent), pre-install Claude Code via postStartCommand, mount ~/.claude with consistency=cached, forward the dev server port, and pass ANTHROPIC_API_KEY through from localEnv. Then explain anything you had to assume.

Uruchom go z wnętrza repozytorium, aby Claude czytał Twoje faktyczne pliki zależności, zamiast zgadywać.

Własny Dockerfile

Aby uzyskać większą kontrolę, użyj pliku Dockerfile:

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/typescript-node:20

# Install Claude Code globally
RUN npm install -g @anthropic-ai/claude-code@latest

# Install project-specific tools
RUN apt-get update && apt-get install -y \
    postgresql-client \
    jq \
    && rm -rf /var/lib/apt/lists/*

# Pre-configure Claude Code settings directory
RUN mkdir -p /home/node/.claude

Odwołaj się do niego w devcontainer.json:

{
  "build": {
    "dockerfile": "Dockerfile"
  }
}

GitHub Codespaces

Codespaces udostępniają kontenery deweloperskie hostowane w chmurze, dostępne z przeglądarki lub lokalnego VS Code.

Konfiguracja specyficzna dla Codespaces

{
  "name": "Codespace with Claude Code",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest",
  "secrets": {
    "ANTHROPIC_API_KEY": {
      "description": "API key for Claude Code",
      "documentationUrl": "https://console.anthropic.com/settings/keys"
    }
  },
  "portsAttributes": {
    "3000": {
      "label": "Application",
      "onAutoForward": "openBrowser"
    }
  }
}

Pole secrets prosi programistów o skonfigurowanie klucza API podczas tworzenia Codespace.

Współdzielenie konfiguracji Claude Code

Montowanie lokalnej konfiguracji

Udostępnij swoje lokalne ustawienia Claude Code kontenerowi:

{
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
  ]
}

To udostępnia Twoje sesje, auto-pamięć i osobiste ustawienia kontenerowi. Zmiany w kontenerze są odzwierciedlane na Twoim hoście.

Konfiguracja na poziomie projektu

Ponieważ .claude/settings.json, .claude/commands/ i .claude/agents/ są częścią Twojego repozytorium, są automatycznie dostępne wewnątrz kontenera. Nie jest potrzebna dodatkowa konfiguracja.

Gotowa konfiguracja devcontainer z pełną integracją Claude Code:

{
  "name": "Full Claude Code Setup",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest && npm install",
  "remoteEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
    "CLAUDE_CODE_USE_BEDROCK": "${localEnv:CLAUDE_CODE_USE_BEDROCK}",
    "AWS_PROFILE": "${localEnv:AWS_PROFILE}"
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.aws,target=/home/node/.aws,type=bind,readonly"
  ]
}

Zagadnienia bezpieczeństwa

Obsługa kluczy API

Nigdy nie koduj na stałe kluczy API w devcontainer.json. Użyj jednego z tych podejść:

Przekazywanie zmiennych środowiskowych: "${localEnv:ANTHROPIC_API_KEY}"
Sekrety Codespace: Konfigurowane per użytkownik w ustawieniach GitHub
Skrypt apiKeyHelper: Generuje klucze dynamicznie z menedżera sekretów

Izolacja sieciowa

Własna sieć Docker plus zmienna środowiskowa proxy to dopiero punkt wyjścia — sama w sobie nie ogranicza ruchu wychodzącego, ponieważ nic nie zmusza ruchu do przejścia przez proxy ani nie blokuje bezpośrednich połączeń:

{
  "runArgs": ["--network=project-network"],
  "remoteEnv": {
    "HTTPS_PROXY": "http://proxy:8080"
  }
}

Aby faktycznie odizolować sieć, użyj firewalla domyślnie odrzucającego (default-deny), który dopuszcza na białą listę wyłącznie domeny potrzebne Claude Code (API Anthropic, Twój rejestr pakietów, Twój host systemu kontroli wersji). Oficjalny referencyjny devcontainer Claude Code robi dokładnie to — zobacz init-firewall.sh, który domyślnie blokuje cały ruch wychodzący i weryfikuje reguły przy starcie kontenera.

Tryb piaskownicy

Claude Code dostarcza natywną piaskownicę, która używa prymitywów na poziomie systemu operacyjnego, aby ograniczyć dostęp do systemu plików i sieci dla narzędzia bash — jest ona jednak opcjonalna, wyłączona dopóki jej nie włączysz, a nie domyślnie aktywna. Nie istnieje zmienna środowiskowa CLAUDE_CODE_SANDBOX; włączanie jej przez remoteEnv nic nie robi.

Włącz piaskownicę z wnętrza Claude Code, uruchamiając polecenie /sandbox, które otwiera menu trybów piaskownicy (i drukuje instrukcje instalacji, jeśli na Linuksie brakuje zależności takich jak bubblewrap lub socat):

> /sandbox

Aby uczynić ją domyślną dla każdego, kto otwiera kontener, skonfiguruj ją pod kluczem sandbox w .claude/settings.json (zacommitowanym do repo). Wewnątrz kontenera piaskownica dodaje obronę w głąb na wierzchu izolacji kontenera — te dwa mechanizmy się uzupełniają, a nie powielają. Pełną referencję ustawień znajdziesz w dokumentacji piaskownicy.

Kiedy to nie działa

Claude Code nie został znaleziony po przebudowie kontenera: postStartCommand uruchamia się po każdym starcie kontenera, ale postCreateCommand tylko podczas tworzenia. Umieść instalację Claude Code w postStartCommand, aby upewnić się, że przetrwa przebudowy.

Zamontowany katalog .claude ma złe uprawnienia: Użytkownicy kontenera mogą różnić się od Twojego użytkownika hosta. Dodaj postStartCommand do naprawienia uprawnień: "sudo chown -R node:node /home/node/.claude".

Klucz API niedostępny w terminalu kontenera: Upewnij się, że używasz ${localEnv:ANTHROPIC_API_KEY} (nie ${containerEnv}). Prefiks localEnv przekazuje zmienne z Twojej maszyny hosta.

Sesje z hosta nie pojawiają się w kontenerze: Sesje są przechowywane według ścieżki katalogu. Jeśli ścieżka projektu różni się między hostem a kontenerem (np. /Users/you/project vs /workspaces/project), sesje nie będą pasować. To oczekiwane zachowanie.

Co dalej

Integracja korporacyjna — Zarządzane ustawienia dla wdrożeń opartych na kontenerach
GitHub Actions — Przepływy pracy CI/CD uzupełniające Twoją konfigurację kontenera deweloperskiego
Konfiguracja proxy — Konfiguracja dostępu do sieci w kontenerach