Back to Details

devcontainers-nix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dev Containers & Nix Environments

Dev Containers 与 Nix 环境

Reproducible, portable development environments that eliminate environment drift.
可复现、可移植的开发环境，消除环境差异问题。

When to Use This Skill

何时使用该技能

Use this skill when:
  • Onboarding new developers (zero-to-productive in minutes)
  • Standardizing toolchains across a team
  • Eliminating "works on my machine" problems
  • Setting up CI environments that match local dev
  • Creating ephemeral, disposable dev environments
在以下场景使用该技能：
  • 新开发者入职（几分钟内从零基础到高效开发）
  • 团队内标准化工具链
  • 解决“在我机器上能运行”的问题
  • 设置与本地开发环境一致的CI环境
  • 创建临时、可丢弃的开发环境

Dev Containers

Dev Containers

Basic Configuration

基础配置

json
// .devcontainer/devcontainer.json
{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" },
    "ghcr.io/devcontainers/features/python:1": { "version": "3.12" },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {}
  },
  "forwardPorts": [3000, 5432],
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-python.python"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  }
}
json
// .devcontainer/devcontainer.json
{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" },
    "ghcr.io/devcontainers/features/python:1": { "version": "3.12" },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {}
  },
  "forwardPorts": [3000, 5432],
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-python.python"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  }
}

Docker Compose Dev Container

Docker Compose 开发容器

json
// .devcontainer/devcontainer.json
{
  "name": "Full Stack Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000, 5432, 6379],
  "postCreateCommand": "npm install && npx prisma migrate dev"
}
yaml
undefined
json
// .devcontainer/devcontainer.json
{
  "name": "Full Stack Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000, 5432, 6379],
  "postCreateCommand": "npm install && npx prisma migrate dev"
}
yaml
undefined

.devcontainer/docker-compose.yml

.devcontainer/docker-compose.yml

services: app: build: context: .. dockerfile: .devcontainer/Dockerfile volumes: - ..:/workspace:cached command: sleep infinity depends_on: [db, redis]
db: image: postgres:16 environment: POSTGRES_DB: dev POSTGRES_USER: dev POSTGRES_PASSWORD: dev volumes: - pgdata:/var/lib/postgresql/data ports: - "5432:5432"
redis: image: redis:7-alpine ports: - "6379:6379"
volumes: pgdata:
undefined
services: app: build: context: .. dockerfile: .devcontainer/Dockerfile volumes: - ..:/workspace:cached command: sleep infinity depends_on: [db, redis]
db: image: postgres:16 environment: POSTGRES_DB: dev POSTGRES_USER: dev POSTGRES_PASSWORD: dev volumes: - pgdata:/var/lib/postgresql/data ports: - "5432:5432"
redis: image: redis:7-alpine ports: - "6379:6379"
volumes: pgdata:
undefined

Custom Dockerfile

自定义 Dockerfile

dockerfile
undefined
dockerfile
undefined

.devcontainer/Dockerfile

.devcontainer/Dockerfile

FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04
FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04

System dependencies

System dependencies

RUN apt-get update && apt-get install -y
build-essential
curl
git
jq
unzip
&& rm -rf /var/lib/apt/lists/*
RUN apt-get update && apt-get install -y
build-essential
curl
git
jq
unzip
&& rm -rf /var/lib/apt/lists/*

Install project-specific tools

Install project-specific tools

RUN curl -fsSL https://get.opentofu.org/install-opentofu.sh | sh -s -- --install-method standalone RUN curl -LO "https://dl.k8s.io/release/$(curl -sL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
&& install kubectl /usr/local/bin/
RUN curl -fsSL https://get.opentofu.org/install-opentofu.sh | sh -s -- --install-method standalone RUN curl -LO "https://dl.k8s.io/release/$(curl -sL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
&& install kubectl /usr/local/bin/

Non-root user setup

Non-root user setup

USER vscode WORKDIR /workspace
undefined
USER vscode WORKDIR /workspace
undefined

Nix Flakes

Nix Flakes

Basic Flake

基础 Flake 配置

nix
undefined
nix
undefined

flake.nix

flake.nix

{ description = "Project development environment";
inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; flake-utils.url = "github:numtide/flake-utils"; };
outputs = { self, nixpkgs, flake-utils }: flake-utils.lib.eachDefaultSystem (system: let pkgs = nixpkgs.legacyPackages.${system}; in { devShells.default = pkgs.mkShell { buildInputs = with pkgs; [ # Languages nodejs_20 python312 go_1_22 rustc cargo
        # Tools
        docker-compose
        kubectl
        kubernetes-helm
        opentofu
        awscli2
        jq
        yq-go

        # Databases
        postgresql_16
        redis
      ];

      shellHook = ''
        echo "Dev environment loaded"
        export PROJECT_ROOT=$(pwd)
        export PATH="$PROJECT_ROOT/node_modules/.bin:$PATH"
      '';
    };
  }
);
}

```bash
{ description = "Project development environment";
inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; flake-utils.url = "github:numtide/flake-utils"; };
outputs = { self, nixpkgs, flake-utils }: flake-utils.lib.eachDefaultSystem (system: let pkgs = nixpkgs.legacyPackages.${system}; in { devShells.default = pkgs.mkShell { buildInputs = with pkgs; [ # Languages nodejs_20 python312 go_1_22 rustc cargo
        # Tools
        docker-compose
        kubectl
        kubernetes-helm
        opentofu
        awscli2
        jq
        yq-go

        # Databases
        postgresql_16
        redis
      ];

      shellHook = ''
        echo "Dev environment loaded"
        export PROJECT_ROOT=$(pwd)
        export PATH="$PROJECT_ROOT/node_modules/.bin:$PATH"
      '';
    };
  }
);
}

```bash

Enter the dev shell

Enter the dev shell

nix develop
nix develop

Or run a single command

Or run a single command

nix develop --command bash -c "node --version && go version"
nix develop --command bash -c "node --version && go version"

Build and run

Build and run

nix build nix run
undefined
nix build nix run
undefined

Pin Dependencies

固定依赖

bash
undefined
bash
undefined

Lock flake inputs for reproducibility

Lock flake inputs for reproducibility

nix flake lock nix flake update # Update all inputs
nix flake lock nix flake update # Update all inputs

Update a specific input

Update a specific input

nix flake lock --update-input nixpkgs
undefined
nix flake lock --update-input nixpkgs
undefined

Devbox (Nix Made Simple)

Devbox（简化版 Nix）

Devbox wraps Nix with a friendlier interface:
bash
undefined
Devbox 为 Nix 提供了更友好的界面：
bash
undefined

Install Devbox

Install Devbox

curl -fsSL https://get.jetify.com/devbox | bash
curl -fsSL https://get.jetify.com/devbox | bash

Initialize project

Initialize project

devbox init
devbox init

Add packages

Add packages

devbox add nodejs@20 python@3.12 postgresql@16 devbox add go@1.22 kubectl helm
devbox add nodejs@20 python@3.12 postgresql@16 devbox add go@1.22 kubectl helm

Enter shell

Enter shell

devbox shell
devbox shell

Run commands without entering shell

Run commands without entering shell

devbox run node --version
undefined
devbox run node --version
undefined

devbox.json Configuration

devbox.json 配置

json
{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/main/.schema/devbox.schema.json",
  "packages": [
    "nodejs@20",
    "python@3.12",
    "go@1.22",
    "kubectl@1.29",
    "kubernetes-helm@3.14",
    "opentofu@1.8",
    "awscli2@2.15",
    "jq@1.7",
    "postgresql@16",
    "redis@7"
  ],
  "env": {
    "PROJECT_ROOT": "$PWD",
    "DATABASE_URL": "postgresql://localhost:5432/dev"
  },
  "shell": {
    "init_hook": [
      "echo 'Dev environment ready'",
      "npm install --silent 2>/dev/null || true"
    ],
    "scripts": {
      "dev": "npm run dev",
      "test": "npm test",
      "db:start": "pg_ctl -D .devbox/virtenv/postgresql/data start",
      "db:stop": "pg_ctl -D .devbox/virtenv/postgresql/data stop",
      "db:migrate": "npx prisma migrate dev"
    }
  }
}
bash
undefined
json
{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/main/.schema/devbox.schema.json",
  "packages": [
    "nodejs@20",
    "python@3.12",
    "go@1.22",
    "kubectl@1.29",
    "kubernetes-helm@3.14",
    "opentofu@1.8",
    "awscli2@2.15",
    "jq@1.7",
    "postgresql@16",
    "redis@7"
  ],
  "env": {
    "PROJECT_ROOT": "$PWD",
    "DATABASE_URL": "postgresql://localhost:5432/dev"
  },
  "shell": {
    "init_hook": [
      "echo 'Dev environment ready'",
      "npm install --silent 2>/dev/null || true"
    ],
    "scripts": {
      "dev": "npm run dev",
      "test": "npm test",
      "db:start": "pg_ctl -D .devbox/virtenv/postgresql/data start",
      "db:stop": "pg_ctl -D .devbox/virtenv/postgresql/data stop",
      "db:migrate": "npx prisma migrate dev"
    }
  }
}
bash
undefined

Run project scripts

Run project scripts

devbox run dev devbox run test devbox run db:start
devbox run dev devbox run test devbox run db:start

Generate direnv integration (auto-activate on cd)

Generate direnv integration (auto-activate on cd)

devbox generate direnv
devbox generate direnv

Generate Dockerfile from devbox config

Generate Dockerfile from devbox config

devbox generate dockerfile
undefined
devbox generate dockerfile
undefined

Devbox + direnv (Auto-Activate)

Devbox + direnv（自动激活）

bash
undefined
bash
undefined

Install direnv

Install direnv

devbox add direnv
devbox add direnv

Generate .envrc

Generate .envrc

devbox generate direnv
devbox generate direnv

Allow direnv

Allow direnv

direnv allow

```bash
direnv allow

```bash

.envrc (auto-generated)

.envrc (auto-generated)

eval "$(devbox generate direnv --print-envrc)"

Now `cd`-ing into the project automatically loads the environment.
eval "$(devbox generate direnv --print-envrc)"

现在进入项目目录时会自动加载环境。

CI/CD Integration

CI/CD 集成

GitHub Actions with Devbox

GitHub Actions 与 Devbox

yaml
undefined
yaml
undefined

.github/workflows/ci.yml

.github/workflows/ci.yml

name: CI on: [push, pull_request]
jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: jetify-com/devbox-install-action@v0.11.0 with: enable-cache: true - run: devbox run test - run: devbox run lint
undefined
name: CI on: [push, pull_request]
jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: jetify-com/devbox-install-action@v0.11.0 with: enable-cache: true - run: devbox run test - run: devbox run lint
undefined

GitHub Actions with Nix

GitHub Actions 与 Nix

yaml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cachix/install-nix-action@v26
        with:
          nix_path: nixpkgs=channel:nixos-unstable
      - uses: cachix/cachix-action@v14
        with:
          name: my-project
          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
      - run: nix develop --command bash -c "npm ci && npm test"
yaml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cachix/install-nix-action@v26
        with:
          nix_path: nixpkgs=channel:nixos-unstable
      - uses: cachix/cachix-action@v14
        with:
          name: my-project
          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
      - run: nix develop --command bash -c "npm ci && npm test"

GitHub Codespaces

GitHub Codespaces

json
// .devcontainer/devcontainer.json — works in Codespaces
{
  "name": "Codespaces Dev",
  "image": "mcr.microsoft.com/devcontainers/universal:2",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" }
  },
  "postCreateCommand": "npm install",
  "portsAttributes": {
    "3000": { "label": "App", "onAutoForward": "openBrowser" },
    "5432": { "label": "Postgres", "onAutoForward": "ignore" }
  }
}
json
// .devcontainer/devcontainer.json — works in Codespaces
{
  "name": "Codespaces Dev",
  "image": "mcr.microsoft.com/devcontainers/universal:2",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" }
  },
  "postCreateCommand": "npm install",
  "portsAttributes": {
    "3000": { "label": "App", "onAutoForward": "openBrowser" },
    "5432": { "label": "Postgres", "onAutoForward": "ignore" }
  }
}

Comparison

对比

FeatureDev ContainersNix FlakesDevbox
Learning curveLowHighLow
ReproducibilityGood (Docker)ExcellentExcellent (Nix)
SpeedSlow (build image)Fast (cached)Fast (cached)
IDE supportVS Code, JetBrainsAny terminalAny terminal
CI integrationDocker-basedNix actionsDevbox action
Offline supportLimitedFullFull
macOS/Linux/WinAllmacOS/LinuxmacOS/Linux
特性Dev ContainersNix FlakesDevbox
学习曲线低高低
可复现性良好（基于Docker）优秀优秀（基于Nix）
速度慢（构建镜像）快（缓存）快（缓存）
IDE支持VS Code、JetBrains任意终端任意终端
CI集成基于DockerNix动作Devbox动作
离线支持有限完整完整
支持系统macOS/Linux/WindowsmacOS/LinuxmacOS/Linux

Best Practices

最佳实践

  • Pin all tool versions explicitly — never use 
    latest
  • Commit lock files (
    flake.lock
    , 
    devbox.lock
    , etc.)
  • Use direnv for automatic environment activation
  • Cache Nix store in CI (Cachix or GitHub cache)
  • Document setup in README: 
    devbox shell
    or 
    nix develop
  • Keep dev environment close to production (same Node/Python versions)
  • 明确固定所有工具版本——绝不使用
    latest
  • 提交锁定文件（
    flake.lock
    、
    devbox.lock
    等）
  • 使用direnv实现环境自动激活
  • 在CI中缓存Nix存储（Cachix或GitHub缓存）
  • 在README中记录设置步骤：
    devbox shell
    或
    nix develop
  • 保持开发环境与生产环境一致（相同的Node/Python版本）

Troubleshooting

故障排除

IssueSolution
Nix build slow first timeUse binary cache (Cachix), 
nix develop
caches after first run
Dev Container won't buildCheck Docker disk space, rebuild with 
--no-cache
Package not in NixpkgsSearch at search.nixos.org, or use 
fetchFromGitHub
overlay
Devbox hash mismatchRun 
devbox update
, delete 
.devbox/
and re-init
direnv not activatingRun 
direnv allow
, check shell hook is installed
问题解决方案
Nix首次构建缓慢使用二进制缓存（Cachix），
nix develop
首次运行后会缓存
Dev Container无法构建检查Docker磁盘空间，使用
--no-cache
重新构建
包不在Nixpkgs中在search.nixos.org搜索，或使用
fetchFromGitHub
覆盖
Devbox哈希不匹配运行
devbox update
，删除
.devbox/
并重新初始化
direnv未激活运行
direnv allow
，检查shell钩子是否已安装

Related Skills

相关技能

  • docker-management — Container image optimization
  • github-actions — CI/CD pipeline setup
  • linux-administration — System-level tooling
  • docker-management — 容器镜像优化
  • github-actions — CI/CD流水线设置
  • linux-administration — 系统级工具