devcontainer-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Devcontainer Setup Skill

Devcontainer 搭建技能

Creates a pre-configured devcontainer with Claude Code and language-specific tooling.

创建预配置的、包含Claude Code和特定语言工具的开发容器。

When to Use

适用场景

User asks to "set up a devcontainer" or "add devcontainer support"
User wants a sandboxed Claude Code development environment
User needs isolated development environments with persistent configuration

用户要求“搭建devcontainer”或“添加devcontainer支持”
用户需要沙箱化的Claude Code开发环境
用户需要带有持久化配置的隔离开发环境

When NOT to Use

不适用场景

User already has a devcontainer configuration and just needs modifications
User is asking about general Docker or container questions
User wants to deploy production containers (this is for development only)

用户已有devcontainer配置，仅需修改
用户询问通用Docker或容器相关问题
用户想要部署生产容器（本技能仅用于开发环境）

Workflow

工作流程

mermaid

flowchart TB
    start([User requests devcontainer])
    recon[1. Project Reconnaissance]
    detect[2. Detect Languages]
    generate[3. Generate Configuration]
    write[4. Write files to .devcontainer/]
    done([Done])

    start --> recon
    recon --> detect
    detect --> generate
    generate --> write
    write --> done

mermaid

flowchart TB
    start([User requests devcontainer])
    recon[1. Project Reconnaissance]
    detect[2. Detect Languages]
    generate[3. Generate Configuration]
    write[4. Write files to .devcontainer/]
    done([Done])

    start --> recon
    recon --> detect
    detect --> generate
    generate --> write
    write --> done

Phase 1: Project Reconnaissance

阶段1：项目侦察

Infer Project Name

推断项目名称

Check in order (use first match):

```
package.json
```
→
```
name
```
field
```
pyproject.toml
```
→
```
project.name
```
```
Cargo.toml
```
→
```
package.name
```
```
go.mod
```
→ module path (last segment after
```
/
```
)
Directory name as fallback

Convert to slug: lowercase, replace spaces/underscores with hyphens.

按以下顺序检查（使用第一个匹配项）：

```
package.json
```
→
```
name
```
字段
```
pyproject.toml
```
→
```
project.name
```
```
Cargo.toml
```
→
```
package.name
```
```
go.mod
```
→ 模块路径（最后一个
```
/
```
后的部分）
回退使用目录名称

转换为短标识：小写，将空格/下划线替换为连字符。

Detect Language Stack

检测语言栈

Language	Detection Files
Python	`pyproject.toml` , `*.py`
Node/TypeScript	`package.json` , `tsconfig.json`
Rust	`Cargo.toml`
Go	`go.mod` , `go.sum`

语言	检测文件
Python	`pyproject.toml` , `*.py`
Node/TypeScript	`package.json` , `tsconfig.json`
Rust	`Cargo.toml`
Go	`go.mod` , `go.sum`

Multi-Language Projects

多语言项目

If multiple languages are detected, configure all of them in the following priority order:

Python - Primary language, uses Dockerfile for uv + Python installation
Node/TypeScript - Uses devcontainer feature
Rust - Uses devcontainer feature
Go - Uses devcontainer feature

For multi-language

postCreateCommand

, chain all setup commands:

uv run /opt/post_install.py && uv sync && npm ci

Extensions and settings from all detected languages should be merged into the configuration.

如果检测到多种语言，按以下优先级顺序配置所有语言：

Python - 主语言，使用Dockerfile安装uv + Python
Node/TypeScript - 使用devcontainer功能
Rust - 使用devcontainer功能
Go - 使用devcontainer功能

对于多语言的

postCreateCommand

，将所有设置命令链式组合：

uv run /opt/post_install.py && uv sync && npm ci

所有检测到语言的扩展和设置应合并到配置中。

Phase 2: Generate Configuration

阶段2：生成配置

Start with base templates from

resources/

directory. Substitute:

```
{{PROJECT_NAME}}
```
→ Human-readable name (e.g., "My Project")
```
{{PROJECT_SLUG}}
```
→ Slug for volumes (e.g., "my-project")

Then apply language-specific modifications below.

从

resources/

目录的基础模板开始，替换以下占位符：

```
{{PROJECT_NAME}}
```
→ 人类可读的名称（例如："My Project"）
```
{{PROJECT_SLUG}}
```
→ 用于卷的短标识（例如："my-project"）

然后应用以下特定语言的修改。

Base Template Features

基础模板特性

The base template includes:

Claude Code with marketplace plugins (anthropics/skills, trailofbits/skills)
Python 3.13 via uv (fast binary download)
Node 22 via fnm (Fast Node Manager)
ast-grep for AST-based code search
Network isolation tools (iptables, ipset) with NET_ADMIN capability
Modern CLI tools: ripgrep, fd, fzf, tmux, git-delta

基础模板包含：

Claude Code 及市场插件（anthropics/skills, trailofbits/skills）
Python 3.13（通过uv快速二进制下载）
Node 22（通过fnm，即Fast Node Manager）
ast-grep 用于基于AST的代码搜索
网络隔离工具（iptables, ipset），具备NET_ADMIN权限
现代CLI工具：ripgrep, fd, fzf, tmux, git-delta

Language-Specific Sections

特定语言配置部分

Python Projects

Python项目

Detection:

pyproject.toml

requirements.txt

setup.py

, or

*.py

files

Dockerfile additions:

The base Dockerfile already includes Python 3.13 via uv. If a different version is required (detected from

pyproject.toml

), modify the Python installation:

dockerfile

undefined

检测依据：

pyproject.toml

requirements.txt

setup.py

或

*.py

文件

Dockerfile新增内容：

基础Dockerfile已通过uv包含Python 3.13。如果需要不同版本（从

pyproject.toml

检测），修改Python安装命令：

dockerfile

undefined

Install Python via uv (fast binary download, not source compilation)

RUN uv python install <version> --default


**devcontainer.json extensions:**

Add to `customizations.vscode.extensions`:
```json
"ms-python.python",
"ms-python.vscode-pylance",
"charliermarsh.ruff"

Add to

customizations.vscode.settings

json

"python.defaultInterpreterPath": ".venv/bin/python",
"[python]": {
  "editor.defaultFormatter": "charliermarsh.ruff",
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

postCreateCommand: If

pyproject.toml

exists, chain commands:

rm -rf .venv && uv sync && uv run /opt/post_install.py

RUN uv python install <version> --default


**devcontainer.json扩展：**

添加到`customizations.vscode.extensions`：
```json
"ms-python.python",
"ms-python.vscode-pylance",
"charliermarsh.ruff"

添加到

customizations.vscode.settings

：

json

"python.defaultInterpreterPath": ".venv/bin/python",
"[python]": {
  "editor.defaultFormatter": "charliermarsh.ruff",
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

postCreateCommand： 如果存在

pyproject.toml

，链式组合命令：

rm -rf .venv && uv sync && uv run /opt/post_install.py

Node/TypeScript Projects

Node/TypeScript项目

Detection:

package.json

tsconfig.json

No Dockerfile additions needed: The base template includes Node 22 via fnm (Fast Node Manager).

devcontainer.json extensions:

Add to

customizations.vscode.extensions

json

"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"

Add to

customizations.vscode.settings

json

"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
  "source.fixAll.eslint": "explicit"
}

postCreateCommand: Detect package manager from lockfile and chain with base command:

pnpm-lock.yaml

→

uv run /opt/post_install.py && pnpm install --frozen-lockfile

yarn.lock

→

uv run /opt/post_install.py && yarn install --frozen-lockfile

package-lock.json

→

uv run /opt/post_install.py && npm ci

No lockfile →

uv run /opt/post_install.py && npm install

检测依据：

package.json

或

tsconfig.json

无需修改Dockerfile： 基础模板已通过fnm（Fast Node Manager）包含Node 22。

devcontainer.json扩展：

添加到

customizations.vscode.extensions

：

json

"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"

添加到

customizations.vscode.settings

：

json

"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
  "source.fixAll.eslint": "explicit"
}

postCreateCommand： 从锁文件检测包管理器并与基础命令链式组合：

pnpm-lock.yaml

→

uv run /opt/post_install.py && pnpm install --frozen-lockfile

yarn.lock

→

uv run /opt/post_install.py && yarn install --frozen-lockfile

package-lock.json

→

uv run /opt/post_install.py && npm ci

无锁文件 →

uv run /opt/post_install.py && npm install

Rust Projects

Rust项目

Detection:

Cargo.toml

Features to add:

json

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

devcontainer.json extensions:

Add to

customizations.vscode.extensions

json

"rust-lang.rust-analyzer",
"tamasfe.even-better-toml"

Add to

customizations.vscode.settings

json

"[rust]": {
  "editor.defaultFormatter": "rust-lang.rust-analyzer"
}

postCreateCommand: If

Cargo.lock

exists, use locked builds:

uv run /opt/post_install.py && cargo build --locked

If no lockfile, use standard build:

uv run /opt/post_install.py && cargo build

检测依据：

Cargo.toml

需添加的特性：

json

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

devcontainer.json扩展：

添加到

customizations.vscode.extensions

：

json

"rust-lang.rust-analyzer",
"tamasfe.even-better-toml"

添加到

customizations.vscode.settings

：

json

"[rust]": {
  "editor.defaultFormatter": "rust-lang.rust-analyzer"
}

postCreateCommand： 如果存在

Cargo.lock

，使用锁定构建：

uv run /opt/post_install.py && cargo build --locked

如果无锁文件，使用标准构建：

uv run /opt/post_install.py && cargo build

Go Projects

Go项目

Detection:

go.mod

Features to add:

json

"ghcr.io/devcontainers/features/go:1": {
  "version": "latest"
}

devcontainer.json extensions:

Add to

customizations.vscode.extensions

json

"golang.go"

Add to

customizations.vscode.settings

json

"[go]": {
  "editor.defaultFormatter": "golang.go"
},
"go.useLanguageServer": true

postCreateCommand:

uv run /opt/post_install.py && go mod download

检测依据：

go.mod

需添加的特性：

json

"ghcr.io/devcontainers/features/go:1": {
  "version": "latest"
}

devcontainer.json扩展：

添加到

customizations.vscode.extensions

：

json

"golang.go"

添加到

customizations.vscode.settings

：

json

"[go]": {
  "editor.defaultFormatter": "golang.go"
},
"go.useLanguageServer": true

postCreateCommand：

uv run /opt/post_install.py && go mod download

Reference Material

参考资料

For additional guidance, see:

```
references/dockerfile-best-practices.md
```
- Layer optimization, multi-stage builds, architecture support
```
references/features-vs-dockerfile.md
```
- When to use devcontainer features vs custom Dockerfile

如需更多指导，请查看：

```
references/dockerfile-best-practices.md
```
- 层优化、多阶段构建、架构支持
```
references/features-vs-dockerfile.md
```
- 何时使用devcontainer特性 vs 自定义Dockerfile

Adding Persistent Volumes

添加持久化卷

Pattern for new mounts in

devcontainer.json

json

"mounts": [
  "source={{PROJECT_SLUG}}-<purpose>-${devcontainerId},target=<container-path>,type=volume"
]

Common additions:

source={{PROJECT_SLUG}}-cargo-${devcontainerId},target=/home/vscode/.cargo,type=volume

(Rust)

source={{PROJECT_SLUG}}-go-${devcontainerId},target=/home/vscode/go,type=volume

(Go)

在

devcontainer.json

中添加新挂载的格式：

json

"mounts": [
  "source={{PROJECT_SLUG}}-<purpose>-${devcontainerId},target=<container-path>,type=volume"
]

常见新增项：

source={{PROJECT_SLUG}}-cargo-${devcontainerId},target=/home/vscode/.cargo,type=volume

（Rust）

source={{PROJECT_SLUG}}-go-${devcontainerId},target=/home/vscode/go,type=volume

（Go）

Output Files

输出文件

Generate these files in the project's

.devcontainer/

directory:

```
Dockerfile
```
- Container build instructions
```
devcontainer.json
```
- VS Code/devcontainer configuration
```
post_install.py
```
- Post-creation setup script
```
.zshrc
```
- Shell configuration
```
install.sh
```
- CLI helper for managing the devcontainer (
```
devc
```
command)

在项目的

.devcontainer/

目录中生成以下文件：

```
Dockerfile
```
- 容器构建指令
```
devcontainer.json
```
- VS Code/devcontainer配置
```
post_install.py
```
- 创建后设置脚本
```
.zshrc
```
- Shell配置
```
install.sh
```
- 用于管理devcontainer的CLI助手（
```
devc
```
命令）

Validation Checklist

验证清单

Before presenting files to the user, verify:

All
```
{{PROJECT_NAME}}
```
placeholders are replaced with the human-readable name
All
```
{{PROJECT_SLUG}}
```
placeholders are replaced with the slugified name
JSON syntax is valid in
```
devcontainer.json
```
(no trailing commas, proper nesting)
Language-specific extensions are added for all detected languages
```
postCreateCommand
```
includes all required setup commands (chained with
```
&&
```
)

在向用户展示文件前，请验证：

所有
```
{{PROJECT_NAME}}
```
占位符已替换为人类可读名称
所有
```
{{PROJECT_SLUG}}
```
占位符已替换为短标识名称
```
devcontainer.json
```
中的JSON语法有效（无尾随逗号、嵌套正确）
为所有检测到的语言添加了特定语言扩展
```
postCreateCommand
```
包含所有必要的设置命令（通过
```
&&
```
链式组合）

User Instructions

用户操作指引

After generating, inform the user:

How to start: "Open in VS Code and select 'Reopen in Container'"
Alternative:
```
devcontainer up --workspace-folder .
```

CLI helper: Run

.devcontainer/install.sh self-install

to add the

devc

command to PATH

生成文件后，告知用户：

启动方式：“在VS Code中打开并选择‘在容器中重新打开’”
替代方式：
```
devcontainer up --workspace-folder .
```

CLI助手：运行

.devcontainer/install.sh self-install

将

devc

命令添加到PATH