devcontainers-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Devcontainers Best Practices

Dev Container最佳实践

This skill guides you to the right documentation and references for the Development Container ecosystem. Use it when working with

devcontainer.json

, selecting Features or Templates, or when the user asks about dev containers, containers.dev, or supporting tools.

本技能为你指引Development Container生态系统的相关文档与参考资料。当你处理

devcontainer.json

、选择Features或Templates，或是用户询问开发容器、containers.dev或相关支持工具时，均可使用本技能。

Quick start

快速入门

Minimal

devcontainer.json

using an image and a Feature:

"image": "mcr.microsoft.com/devcontainers/base:ubuntu"

"features": { "ghcr.io/devcontainers/features/git:1": {} }

. For property details and validation, see Quick lookup item 1 and references/schema.md.

使用镜像和Feature的最简

devcontainer.json

示例：

"image": "mcr.microsoft.com/devcontainers/base:ubuntu"

"features": { "ghcr.io/devcontainers/features/git:1": {} }

。如需了解属性详情与验证方法，请查看快速查询第1项和references/schema.md。

When to use this skill

适用场景

Editing or validating
```
devcontainer.json
```
Looking up a property (syntax, type, tool support)
Choosing or referencing a Feature or Template
Checking which tools support the spec or have tool-specific properties/limitations
Understanding the spec (lifecycle, merge logic, image metadata)
Authoring or publishing a Dev Container Feature (see the Authoring section in references/features.md and the containers.dev authoring guide)
Configuring multiple dev containers (multi-project, shared Compose); see references/tools.md and VS Code / multi-container docs

编辑或验证
```
devcontainer.json
```
查询属性（语法、类型、工具支持情况）
选择或参考Feature或Template
查看哪些工具支持该规范，或是具备特定工具属性/限制
理解规范（生命周期、合并逻辑、镜像元数据）
编写或发布Dev Container Feature（请查看references/features.md中的编写章节，以及containers.dev编写指南）
配置多个开发容器（多项目、共享Compose）；请查看references/tools.md和VS Code / 多容器文档

Canonical sources

权威来源

All content in this skill and its references is traceable to these sources:

Spec and reference: containers.dev/implementors/spec, containers.dev/implementors/json_reference
Schema: containers.dev/implementors/json_schema
Guides: containers.dev/guides (prebuilds, using Dockerfile/Compose, Feature authoring best practices, GitLab CI)
Supporting tools: devcontainers.github.io/supporting
Features: containers.dev/implementors/features, github.com/devcontainers/features
Templates: containers.dev/implementors/templates, github.com/devcontainers/templates

本技能及其参考资料中的所有内容均来自以下权威来源：

规范与参考：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

Reference files

参考文件

Detailed material is in the

references/

directory. Load only what you need.

Need	File
When to use the full spec, key concepts, merge logic, lifecycle	references/spec.md
JSON reference vs schema, canonical URLs, how to validate	references/schema.md
Supporting tools, tool-specific properties, limitations	references/tools.md
VS Code workflows, requirements, prebuild, ports, extensions, limitations, dotfiles, managing containers	references/vscode-containers.md
Tips and tricks (OS, Git, performance, troubleshooting, profile persistence, reporting)	references/tips-and-tricks.md
Official Features, OCI refs, versioning, options, install order, authoring Features	references/features.md
Official Templates, when to use template vs Feature vs Dockerfile	references/templates.md

详细内容位于

references/

目录下，请按需查阅。

需求	文件
何时使用完整规范、核心概念、合并逻辑、生命周期	references/spec.md
JSON参考与schema对比、标准URL、验证方法	references/schema.md
支持工具、特定工具属性、限制	references/tools.md
VS Code工作流、要求、预构建、端口、扩展、限制、dotfiles、容器管理	references/vscode-containers.md
技巧与窍门（操作系统、Git、性能、故障排查、配置持久化、问题反馈）	references/tips-and-tricks.md
官方Features、OCI引用、版本控制、选项、安装顺序、编写Features	references/features.md
官方Templates、何时使用Template/Feature/Dockerfile	references/templates.md

Quick lookup

快速查询

Property or behavior in devcontainer.json
Use the Dev Container metadata reference (or references/spec.md) for property-by-property details. For validation, use the devcontainer.json schema or Dev Container CLI; see references/schema.md.
Tool support or tool-specific settings
Check devcontainers.github.io/supporting for the list of tools,
```
customizations.*
```
(e.g.
```
customizations.vscode
```
,
```
customizations.codespaces
```
), and limitations. Summary in references/tools.md.
Advanced scenarios (env vars, mounts, performance, non-root user, remote Docker, multiple containers, Git credentials)
See VS Code Advanced container configuration. Summary and workflow links in references/vscode-containers.md.
Multiple dev containers (multi-project, shared Docker Compose)
See references/tools.md “Multiple containers / multi-project” and Chris Ayers – Multiple dev containers.
OS-specific or troubleshooting (Git, Docker Desktop, cleanup, logs)
See VS Code Dev Containers Tips and Tricks. Summary in references/tips-and-tricks.md.
Feature ID, options, or install order
Official Features: containers.dev/features, github.com/devcontainers/features. OCI refs:
```
ghcr.io/devcontainers/features/<name>:<version>
```
. Details in references/features.md. For authoring Features, see the Authoring section there and containers.dev/guide/feature-authoring-best-practices.
Template or "template vs Feature vs Dockerfile"
Official Templates: containers.dev/templates, github.com/devcontainers/templates. When to use which: references/templates.md.
Spec concepts (lifecycle, merge, image metadata)
Full spec: containers.dev/implementors/spec. Summary: references/spec.md.

devcontainer.json中的属性或行为
如需了解逐个属性的详细信息，请使用Dev Container元数据参考（或references/spec.md）。如需验证，请使用devcontainer.json schema或Dev Container CLI；详情请查看references/schema.md。
工具支持或特定工具设置
请查看devcontainers.github.io/supporting获取工具列表、
```
customizations.*
```
（如
```
customizations.vscode
```
、
```
customizations.codespaces
```
）及限制信息。摘要内容见references/tools.md。
高级场景（环境变量、挂载、性能、非root用户、远程Docker、多容器、Git凭据）
请查看VS Code高级容器配置。摘要与工作流链接见references/vscode-containers.md。
多个开发容器（多项目、共享Docker Compose）
请查看references/tools.md中的“多容器/多项目”章节，以及Chris Ayers – 多开发容器。
特定操作系统或故障排查（Git、Docker Desktop、清理、日志）
请查看VS Code Dev Container技巧与窍门。摘要内容见references/tips-and-tricks.md。
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。
Template或“Template vs Feature vs Dockerfile”对比
官方Templates：containers.dev/templates, github.com/devcontainers/templates。适用场景对比见references/templates.md。
规范概念（生命周期、合并、镜像元数据）
完整规范：containers.dev/implementors/spec。摘要内容见references/spec.md。

Best practices (from official docs)

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

Only apply recommendations that are stated in the spec or official devcontainer documentation; cite the source when relevant.

Environment variables: Prefer
```
containerEnv
```
over
```
remoteEnv
```
when possible so all processes in the container see the variable and it is not client-specific. Use
```
remoteEnv
```
when the value is not static and you want to avoid rebuilding. (Dev Container metadata reference – containerEnv/remoteEnv.)
Port forwarding: In most cases use the
```
forwardPorts
```
property rather than
```
appPort
```
; forwarded ports behave like localhost to the application. Use
```
appPort
```
(or Docker Compose
```
ports
```
) when you need published/network-visible ports. (VS Code – Forwarding or publishing a port, Dev Container metadata reference.)
Pre-build when possible: Pre-building images (e.g. with Dev Container CLI or GitHub Actions) speeds up startup and lets you pin tool versions; image metadata can be inherited so repos need only a minimal
```
devcontainer.json
```
. (VS Code – Pre-building dev container images, containers.dev/guides.)
Security and trust: Dev container configs and images can run arbitrary commands. Only use configs and images from trusted sources. For sandboxing and security context, see the spec and community articles (e.g. The Red Guild – Where do you run your code with attribution).
Feature versions: To pin to a specific version, append it to the Feature ID (e.g. from the versions list). The
```
:latest
```
tag is applied implicitly if omitted. (Features – containers.dev.)
Rebuild after changes: After changing the dev container configuration, rebuild so tools pick up changes (e.g. "Dev Containers: Rebuild Container" or "Codespaces: Rebuild Container" in the command palette, in VS Code or compatible editors such as Cursor). (VS Code Dev Containers extension, GitHub Codespaces.)
Lifecycle script order: Creation scripts run in this order:
```
onCreateCommand
```
→
```
updateContentCommand
```
→
```
postCreateCommand
```
. If one fails, later scripts are not run. (Dev Container metadata reference – Lifecycle scripts.)

When the spec or official docs do not state a recommendation, do not present it as a best practice; either omit it or phrase it as a suggestion with a clear citation.

Optional / community guidance: Community articles (e.g. Daytona – Ultimate guide to dev containers) suggest practices such as keeping images lightweight, caching dependencies, and using Docker Compose for multi-service setups. Use with attribution and prefer spec/official docs when they conflict.

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

环境变量：尽可能优先使用
```
containerEnv
```
而非
```
remoteEnv
```
，这样容器内的所有进程都能看到该变量，且它不依赖客户端。当值非静态且你希望避免重新构建时，使用
```
remoteEnv
```
。（Dev Container元数据参考 – containerEnv/remoteEnv）
端口转发：大多数情况下使用
```
forwardPorts
```
属性而非
```
appPort
```
；转发的端口对应用程序来说如同本地主机端口。当你需要公开/网络可见的端口时，使用
```
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进行多服务配置。使用时请注明出处，当与规范/官方文档冲突时，优先遵循规范/官方文档。

Summary

总结

Use this skill when editing
```
devcontainer.json
```
, choosing Features/Templates, authoring Features, or answering questions about dev containers or containers.dev.
Resolve questions via the canonical URLs above and the reference files under references/.
Best practices: cite containers.dev or devcontainers.github.io; only include guidance that appears there. For OS-specific or troubleshooting issues, consult VS Code Dev Containers Tips and Tricks and references/tips-and-tricks.md.

当你编辑
```
devcontainer.json
```
、选择Features/Templates、编写Features，或是解答开发容器或containers.dev相关问题时，使用本技能。
通过上述权威URL及references/下的参考文件解决问题。
最佳实践：引用containers.dev或devcontainers.github.io的内容；仅包含其中明确说明的指南。如需了解特定操作系统或故障排查问题，请查阅VS Code Dev Container技巧与窍门和references/tips-and-tricks.md。