devcontainers-best-practices

Devcontainers 最佳实践

此技能将指导你查阅 Development Container 生态系统的相关文档和参考资料。在使用 devcontainer.json、选择 Feature 或 Template，或用户询问 dev 容器、containers.dev 或支持工具时，请使用此技能。

快速入门

使用镜像和 Feature 的最简 devcontainer.json："image": "mcr.microsoft.com/devcontainers/base:ubuntu"、"features": { "ghcr.io/devcontainers/features/git:1": {} }。有关属性详情和验证，请参阅快速查阅中的第 1 项和 references/schema.md。

何时使用此技能

• 编辑或验证 devcontainer.json
• 查找属性（语法、类型、工具支持情况）
• 选择或引用 Feature 或 Template
• 检查哪些工具支持该规范，或具有特定于工具的属性／限制
• 了解规范（生命周期、合并逻辑、镜像元数据）
• 编写或发布 Dev Container Feature（请参阅 references/features.md 中的“编写”部分，以及 containers.dev 编写指南）
• 配置多个 dev 容器（多项目、共享 Compose）；请参阅 references/tools.md 和 VS Code / 多容器文档

权威来源

此技能及其参考资料中的所有内容均可追溯至以下来源：

• 规范和参考：containers.dev/implementors/spec、containers.dev/implementors/json_reference
• Schema：containers.dev/implementors/json_schema
• 指南：containers.dev/guides（预构建、使用 Dockerfile/Compose、Feature 编写最佳实践、GitLab CI）
• 支持工具：devcontainers.github.io/supporting
• Features：containers.dev/implementors/features、github.com/devcontainers/features
• Templates：containers.dev/implementors/templates、github.com/devcontainers/templates

参考文件

详细内容位于 references/ 目录中。只需加载所需内容。

需求	文件
何时使用完整规范、关键概念、合并逻辑、生命周期	references/spec.md
JSON reference 与 schema 的区别、权威 URL、如何验证	references/schema.md
支持工具、特定于工具的属性、限制	references/tools.md
VS Code 工作流、要求、预构建、端口、扩展、限制、dotfiles、容器管理	references/vscode-containers.md
提示与技巧（操作系统、Git、性能、故障排除、配置文件持久化、问题报告）	references/tips-and-tricks.md
官方 Features、OCI 引用、版本控制、选项、安装顺序、Feature 编写	references/features.md
官方 Templates，以及何时使用 Template、Feature 或 Dockerfile	references/templates.md

快速查找

1. devcontainer.json 中的属性或行为
   逐项查看 Dev Container 元数据参考（或 references/spec.md）中的详细信息。验证时，请使用 devcontainer.json 架构或 Dev Container CLI；参见 references/schema.md。

2. 工具支持或特定工具的设置
   查看 devcontainers.github.io/supporting，了解工具列表、customizations.*（例如 customizations.vscode、customizations.codespaces）和限制。摘要见 references/tools.md。

3. 高级场景（环境变量、挂载、性能、非 root 用户、远程 Docker、多个容器、Git 凭据）
   请参阅 VS Code 高级容器配置。摘要和工作流链接见 references/vscode-containers.md。

4. 多个开发容器（多项目、共享 Docker Compose）
   请参阅 references/tools.md 中的“多个容器 / 多项目”以及 Chris Ayers – 多个开发容器。

5. 特定操作系统或故障排查（Git、Docker Desktop、清理、日志）
   请参阅 VS Code 开发容器提示与技巧。摘要见 references/tips-and-tricks.md。

6. Feature ID、选项或安装顺序
   官方 Features：containers.dev/features、github.com/devcontainers/features。OCI 引用：ghcr.io/devcontainers/features/<name>:<version>。详情见 references/features.md。有关 编写 Features，请参阅该文档中的“编写”部分以及 containers.dev/guide/feature-authoring-best-practices。

7. 模板或“模板与 Feature、Dockerfile 的区别”
   官方模板：containers.dev/templates、github.com/devcontainers/templates。有关如何选择，请参阅 references/templates.md。

8. 规范概念（生命周期、合并、镜像元数据）
   完整规范：containers.dev/implementors/spec。摘要：references/spec.md。

最佳实践（来自官方文档）

仅应用规范或官方 devcontainer 文档中明确说明的建议；相关时请注明来源。

• 环境变量：尽可能优先使用 containerEnv 而非 remoteEnv，这样容器中的所有进程都能看到该变量，而且它不会因客户端而异。当值不是静态值，且你希望避免重建时，请使用 remoteEnv。(Dev Container 元数据参考 – containerEnv/remoteEnv.)
• 端口转发：大多数情况下，请使用 forwardPorts 属性，而非 appPort；转发的端口对应用而言表现为 localhost。需要发布端口或让端口可通过网络访问时，请使用 appPort（或 Docker Compose ports）。(VS Code – 转发或发布端口，Dev Container 元数据参考.)
• 尽可能预构建：预构建映像（例如使用 Dev Container CLI 或 GitHub Actions）可以加快启动速度，并让你锁定工具版本；映像元数据可以继承，因此仓库只需使用精简的 devcontainer.json。(VS Code – 预构建开发容器映像，containers.dev/guides.)
• 安全与信任：开发容器配置和映像可以运行任意命令。请仅使用来自可信来源的配置和映像。有关沙盒和安全上下文，请参阅规范和社区文章（例如 The Red Guild – 你的代码在哪里运行，并注明出处）。
• Feature 版本：要锁定特定版本，请将版本号追加到 Feature ID（例如参见 版本列表）。如果省略，系统会隐式应用 :latest 标签。(Features – containers.dev.)
• 更改后重建：更改开发容器配置后，请进行重建，以便工具应用更改（例如，在 VS Code 或 Cursor 等兼容编辑器的命令面板中运行 "Dev Containers: Rebuild Container" 或 "Codespaces: Rebuild Container"）。(VS Code Dev Containers 扩展，GitHub Codespaces.)
• 生命周期脚本顺序：创建脚本按以下顺序运行：onCreateCommand → updateContentCommand → postCreateCommand。如果其中一个脚本失败，后续脚本将不会运行。(Dev Container 元数据参考 – 生命周期脚本.)

如果规范或官方文档没有提出某项建议，请勿将其表述为最佳实践；可以省略，或注明明确来源并将其表述为建议。

**可选／社区指南：**社区文章（例如 Daytona – 开发容器终极指南）会建议一些做法，例如精简映像、缓存依赖项，以及在多服务设置中使用 Docker Compose。引用时请注明出处；如与规范或官方文档冲突，应优先采用后者。

总结

• 编辑 devcontainer.json、选择 Features/Templates、编写 Features，或回答有关开发容器或 containers.dev 的问题时，请使用此技能。
• 通过上述规范 URL 和 references/ 下的参考文件解答问题。
• 最佳实践：引用 containers.dev 或 devcontainers.github.io；仅纳入其中有明确依据的指南。对于特定操作系统的问题或故障排查，请参阅 VS Code 开发容器提示与技巧和 references/tips-and-tricks.md。