devcontainers-nix

用途

devcontainers-nix 用于创建可复现、可移植的开发环境，消除环境漂移。资料说明其适用场景包括：新开发者入职（几分钟内从零到可产出）、在团队内统一工具链、消除“在我机器上能跑”的问题、搭建与本地开发一致的 CI 环境，以及创建临时、可丢弃的开发环境。

主要能力

该技能覆盖三种方案：

Dev Containers：基于容器定义开发环境，支持基础配置、Docker Compose 组合与自定义 Dockerfile。示例中包含 features（node、python、docker-in-docker、kubectl-helm-minikube）、forwardPorts、postCreateCommand、VS Code 扩展与设置、非 root 用户设置等。
Nix flakes：通过 flake.nix 定义 devShell，声明语言与工具（nodejs_20、python312、go_1_22、rustc、cargo、docker-compose、kubectl、kubernetes-helm、opentofu、awscli2、jq、yq-go、postgresql_16、redis 等），并提供 shellHook。支持 nix develop、nix develop --command、nix build、nix run，以及 nix flake lock / update 锁定依赖。
Devbox：以更友好的界面封装 Nix。提供安装命令、devbox init、devbox add、devbox shell、devbox run，以及 devbox.json 配置（packages、env、shell.init_hook、shell.scripts）。还支持 devbox generate direnv 与 devbox generate dockerfile。

此外还包含 direnv 自动激活、GitHub Actions（Devbox 与 Nix 两种）、GitHub Codespaces 集成示例，以及三种方案的对比表、最佳实践与故障排查表。

使用方式

资料给出的典型操作包括：

Dev Containers：编写 .devcontainer/devcontainer.json，可选用镜像、features、forwardPorts、postCreateCommand、customizations；或使用 dockerComposeFile 组合多服务；或编写自定义 Dockerfile。
Nix：编写 flake.nix，运行 nix develop 进入开发 shell，或 nix develop --command 执行单条命令；用 nix flake lock 锁定输入，nix flake update 更新全部输入，nix flake lock --update-input nixpkgs 更新指定输入。
Devbox：安装后 devbox init，devbox add 添加包，devbox shell 进入 shell，devbox run 执行脚本；devbox generate direnv 生成 .envrc，direnv allow 启用自动激活。
CI/CD：GitHub Actions 中可使用 jetify-com/devbox-install-action 或 cachix/install-nix-action 与 cachix/cachix-action，再运行 devbox run 或 nix develop --command。

适用场景

适合需要团队统一工具链、快速入职、CI 与本地一致、临时开发环境的工程团队。对比表显示：Dev Containers 学习曲线低、可复现性良好（Docker）、速度较慢（构建镜像）、IDE 支持 VS Code 与 JetBrains、CI 基于 Docker、离线支持有限、支持 macOS/Linux/Windows；Nix flakes 学习曲线高、可复现性极佳、速度快（缓存）、任意终端、Nix actions、完全离线、支持 macOS/Linux；Devbox 学习曲线低、可复现性极佳（Nix）、速度快（缓存）、任意终端、Devbox action、完全离线、支持 macOS/Linux。

限制与安全边界

资料明确的安全与执行边界：

Devcontainer features、生命周期钩子、Nix shell 钩子、direnv 与依赖安装器都会执行代码；激活前需检查完整配置、锁定输入与来源。
不要运行会变动的下载安装器，不要通过删除或重建状态来接受哈希不匹配；先验证发布者/版本与完整性。
避免对不可信仓库使用特权 Docker-in-Docker 与宿主套接字。
默认不要将生产凭据传入开发环境。
离线运行需要每个依赖/产物已在本地可用；仅有锁文件不够。
nix build/run 需要相应输出，而仅 devShell 的示例并未定义这些输出。
指南会针对真实环境执行：应用任何内容前确认目标、影响范围与回滚计划。
未经明确批准，绝不部署到生产环境。
本文档为纯文档导入：上游脚本与模板未随附。

最佳实践与故障排查

最佳实践包括：显式固定所有工具版本（绝不使用 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 钩子是否安装）。

技能介绍

用途