mcpField
D
devcontainers-nix

devcontainers-nix

github.com/bagelhole开发1.2k307 次安装23 周前更新
代码仓库

关于 devcontainers-nix

这项技能指南介绍如何使用 Dev Containers、Nix Flakes 和 Devbox 创建可复现的开发环境，适合统一本地与 CI 工具链的开发者和团队，并提供配置、自动激活与自动化范例。

主要功能

  1. 01使用 Docker 配置 Dev Containers
  2. 02通过 Nix Flakes 固定环境依赖
  3. 03使用 Devbox 管理软件包与脚本
  4. 04通过 direnv 自动激活环境
  5. 05将环境接入 CI 和 Codespaces

适用场景

  1. 01统一开发团队的工具链
  2. 02使本地开发环境与 CI 保持一致
  3. 03为新成员准备已配置的工作区
  4. 04创建临时开发环境

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bagelhole/devops-security-agent-skills --skill devcontainers-nix

安装后在 Claude Code 中输入/devcontainers-nix确认已加载。

详细介绍

Dev Containers 与 Nix 环境

可复现、可移植的开发环境，消除环境漂移。

何时使用此技能

在以下情况使用此技能：

  • 新开发者入职（几分钟内即可从零开始高效工作）
  • 在团队内统一工具链
  • 消除“在我的机器上能运行”的问题
  • 设置与本地开发环境一致的 CI 环境
  • 创建临时、可丢弃的开发环境

Dev Containers

基本配置
// .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
// .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"
}

# .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:
自定义 Dockerfile
# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04

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

# 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/

# Non-root user setup
USER vscode
WORKDIR /workspace

Nix Flakes

基本 Flake
# 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"
          '';
        };
      }
    );
}

# Enter the dev shell
nix develop

# Or run a single command
nix develop --command bash -c "node --version && go version"

# Build and run
nix build
nix run
锁定依赖项
# Lock flake inputs for reproducibility
nix flake lock
nix flake update  # Update all inputs

# Update a specific input
nix flake lock --update-input nixpkgs

Devbox（让 Nix 更简单）

Devbox 以更友好的界面封装 Nix：

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

# Initialize project
devbox init

# Add packages
devbox add nodejs@20 [email protected] postgresql@16
devbox add [email protected] kubectl helm

# Enter shell
devbox shell

# Run commands without entering shell
devbox run node --version
devbox.json 配置
{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/main/.schema/devbox.schema.json",
  "packages": [
    "nodejs@20",
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "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"
    }
  }
}

# Run project scripts
devbox run dev
devbox run test
devbox run db:start

# Generate direnv integration (auto-activate on cd)
devbox generate direnv

# Generate Dockerfile from devbox config
devbox generate dockerfile
Devbox + direnv（自动激活）
# Install direnv
devbox add direnv

# Generate .envrc
devbox generate direnv

# Allow direnv
direnv allow

# .envrc (auto-generated)
eval "$(devbox generate direnv --print-envrc)"

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

CI/CD 集成

使用 Devbox 的 GitHub Actions
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jetify-com/[email protected]
        with:
          enable-cache: true
      - run: devbox run test
      - run: devbox run lint
使用 Nix 的 GitHub Actions
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
// .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" }
  }
}

对比

特性Dev ContainersNix FlakesDevbox
学习曲线低高低
可复现性良好（Docker）极佳极佳（Nix）
速度慢（构建镜像）快（有缓存）快（有缓存）
IDE 支持VS Code、JetBrains任意终端任意终端
CI 集成基于 DockerNix actionsDevbox action
离线支持有限完整完整
macOS/Linux/Win全部macOS/LinuxmacOS/Linux

最佳实践

  • 明确锁定所有工具版本，切勿使用 latest
  • 提交锁文件（flake.lock、devbox.lock 等）
  • 使用 direnv 自动激活环境
  • 在 CI 中缓存 Nix store（Cachix 或 GitHub cache）
  • 在 README 中说明设置方法：devbox shell 或 nix develop
  • 让开发环境尽可能贴近生产环境（使用相同的 Node/Python 版本）

故障排除

问题解决方案
Nix 首次构建速度较慢使用二进制缓存（Cachix）；首次运行后，nix develop 会缓存结果
Dev Container 无法构建检查 Docker 磁盘空间；使用 --no-cache 重新构建
Nixpkgs 中没有所需的软件包在 search.nixos.org 上搜索，或使用 fetchFromGitHub overlay
Devbox 哈希不匹配运行 devbox update，删除 .devbox/ 并重新初始化
direnv 未激活运行 direnv allow，检查是否已安装 shell hook

相关技能

评论

支持 Markdown