devcontainer-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DevContainer Helper

DevContainer 助手

This skill assists in creating and managing

devcontainer.json

files for consistent development environments.

本技能可协助创建和管理

devcontainer.json

文件，以构建一致的开发环境。

Workflow

工作流

1. specific Requirements

1. 明确需求

Before generating the file, determine the user's needs:

Base Environment: Do they want a pre-built image (e.g., Ubuntu, Python, Node), a custom
```
Dockerfile
```
, or a
```
docker-compose.yml
```
setup?
Languages & Tools: What languages (Node.js, Python, Go, Rust, etc.) and tools (Git, CLI utilities) are needed?
Extensions: Are there specific VS Code extensions required?
Ports: What ports need to be forwarded?

生成文件前，先确定用户的需求：

基础环境：用户是想要预构建镜像（例如Ubuntu、Python、Node）、自定义
```
Dockerfile
```
，还是
```
docker-compose.yml
```
配置？
语言与工具：需要哪些语言（Node.js、Python、Go、Rust等）和工具（Git、CLI实用程序）？
扩展：是否需要特定的VS Code扩展？
端口：需要转发哪些端口？

2. Generate Configuration

2. 生成配置

Use the template in

assets/devcontainer-template.json

as a starting point.

For Image-based (Simplest): Use the

image

property. Add

features

for additional tools.

For Dockerfile: Use

build.dockerfile

property pointing to their Dockerfile.

For Docker Compose: Use

dockerComposeFile

and

service

properties.

以

assets/devcontainer-template.json

中的模板为起点。

基于镜像的方式（最简单）： 使用

image

属性。添加

features

来集成额外工具。

基于Dockerfile的方式： 使用

build.dockerfile

属性指向用户的Dockerfile。

基于Docker Compose的方式： 使用

dockerComposeFile

和

service

属性。

3. Service Architecture Principles

3. 服务架构原则

Prefer Sidecars over In-Container Tools: For databases, caches, or message brokers, use dedicated services in
```
docker-compose.yml
```
rather than installing them via
```
Dockerfile
```
or
```
features
```
. This improves build times, resource isolation, and container startup performance.
Sidecars over Docker-in-Docker (DinD): When external services are needed for development/testing, prefer sidecar containers over DinD to reduce overhead and avoid the security complexities of privileged containers.

优先使用Sidecar而非容器内工具：对于数据库、缓存或消息代理，优先在
```
docker-compose.yml
```
中使用专用服务，而非通过
```
Dockerfile
```
或
```
features
```
安装。这能提升构建速度、实现资源隔离，并优化容器启动性能。
优先使用Sidecar而非Docker-in-Docker（DinD）：当开发/测试需要外部服务时，优先选择Sidecar容器而非DinD，以减少开销并避免特权容器带来的安全复杂性。

4. Add Features

4. 添加功能特性

Encourage using "Features" over manual

Dockerfile

commands for better maintainability and Dependabot support. Common features:

Node.js:
```
ghcr.io/devcontainers/features/node:1
```
(Use versioned tags like
```
version: "22"
```
to enable automated updates).
Playwright:
```
ghcr.io/devcontainers/features/playwright:1
```
(Crucial for installing OS-level browser dependencies).

pnpm:

ghcr.io/devcontainers-contrib/features/pnpm:2

Docker-in-Docker:

ghcr.io/devcontainers/features/docker-in-docker:2

Git:
```
ghcr.io/devcontainers/features/git:1
```
.

建议优先使用“Features”而非手动编写

Dockerfile

命令，以提升可维护性并支持Dependabot。常见功能特性：

Node.js：
```
ghcr.io/devcontainers/features/node:1
```
（使用带版本的标签，如
```
version: "22"
```
，以启用自动更新）。
Playwright：
```
ghcr.io/devcontainers/features/playwright:1
```
（用于安装系统级浏览器依赖的关键特性）。

pnpm：

ghcr.io/devcontainers-contrib/features/pnpm:2

。

Docker-in-Docker：

ghcr.io/devcontainers/features/docker-in-docker:2

。

Git：
```
ghcr.io/devcontainers/features/git:1
```
。

5. Performance Optimization: "Baking for Speed"

5. 性能优化：“预构建以提速”

Strategy: Move global tool installations (e.g.,
```
npm install -g cli-tool
```
) from
```
postCreateCommand
```
into a custom
```
Dockerfile
```
.
Benefit: This "bakes" the tools into the image layers, making daily container startup significantly faster as these tools are cached rather than re-installed.

Implementation: Reference the

Dockerfile

docker-compose.yml

devcontainer.json

策略：将全局工具安装（例如
```
npm install -g cli-tool
```
）从
```
postCreateCommand
```
移至自定义
```
Dockerfile
```
中。
优势：这会将工具“预构建”到镜像层中，使日常容器启动速度显著加快，因为这些工具会被缓存而非重新安装。

实现方式：在

docker-compose.yml

或

devcontainer.json

中引用该

Dockerfile

。

6. Lifecycle Scripts vs. Features

6. 生命周期脚本 vs 功能特性

Prefer Features for language runtimes and system tools (to get automated updates).
Use Lifecycle Scripts (
```
postCreateCommand
```
) only for local project setup like
```
pnpm install
```
or database migrations.
Permissions: Use specialized features or
```
remoteUser
```
context to handle volume permission issues instead of manual
```
chown
```
in scripts where possible.

优先使用功能特性：对于语言运行时和系统工具（以获取自动更新）。
使用生命周期脚本（
```
postCreateCommand
```
）仅用于本地项目设置，如
```
pnpm install
```
或数据库迁移。
权限处理：尽可能使用专用功能特性或
```
remoteUser
```
上下文来处理卷权限问题，而非在脚本中手动执行
```
chown
```
命令。

7. Automation & Dependabot

7. 自动化与Dependabot

Always recommend adding
```
devcontainers
```
to
```
.github/dependabot.yml
```
when using Features. This ensures the dev environment stays up-to-date automatically.

当使用Features时，始终建议将
```
devcontainers
```
添加到
```
.github/dependabot.yml
```
中。这能确保开发环境自动保持最新状态。

References

参考资料

See references/cheatsheet.md for a list of common

devcontainer.json

properties and valid values.

查看references/cheatsheet.md获取常见

devcontainer.json

属性及有效值列表。",