Back to Details

devcontainer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Devcontainer Diagnostic

Devcontainer 诊断

Diagnose devcontainer and Docker development environment problems. Help create reproducible, fast-starting development environments that work consistently across VS Code, GitHub Codespaces, and team members.
诊断devcontainer和Docker开发环境问题。帮助创建可复现、启动快速的开发环境，确保在VS Code、GitHub Codespaces以及团队成员的设备上表现一致。

When to Use This Skill

何时使用此技能

Use this skill when:
  • Setting up a new devcontainer
  • Container startup is too slow
  • Configuration errors or conflicts
  • Different behavior in VS Code vs Codespaces
  • Multi-service development environment needed
Do NOT use this skill when:
  • Writing application code
  • Deploying to production
  • Configuring CI/CD pipelines
在以下场景使用此技能：
  • 搭建新的devcontainer
  • 容器启动过慢
  • 配置错误或冲突
  • VS Code与Codespaces中的表现不一致
  • 需要多服务开发环境
请勿在以下场景使用此技能：
  • 编写应用代码
  • 部署到生产环境
  • 配置CI/CD流水线

Core Principle

核心原则

Development containers should provide instant productivity. Every configuration choice affects startup time, reproducibility, and team onboarding. Make these trade-offs explicit.
开发容器应能实现即时高效开发。每一项配置选择都会影响启动时间、可复现性和团队上手速度。要明确这些取舍。

Diagnostic States

诊断状态

DV0: No Devcontainer Strategy

DV0：无Devcontainer策略

Symptoms: Manual setup, "check the README", works on one machine fails on others
Interventions:
  • Start with pre-built devcontainer base image
  • Use 
    assets/devcontainer-simple.md
    template
症状： 手动搭建、“查看README文档”、在一台机器上可用但在其他机器上失败
干预措施：
  • 从预构建的devcontainer基础镜像开始
  • 使用
    assets/devcontainer-simple.md
    模板

DV1: Slow Container Startup

DV1：容器启动缓慢

Symptoms: 5+ minute startup, heavy postCreateCommand, avoiding rebuilds
Key Questions:
  • How long does startup actually take?
  • What's in postCreateCommand?
  • Are you using prebuilds?
Interventions:
  • Move npm install/pip install to Dockerfile (cached)
  • Use mcr.microsoft.com/devcontainers/* base images
  • Configure prebuilds for team repos
  • Run 
    scripts/analyze-devcontainer.ts
症状： 启动时间超过5分钟、postCreateCommand任务繁重、避免重新构建
关键问题：
  • 实际启动时间是多久？
  • postCreateCommand中包含哪些内容？
  • 是否使用预构建功能？
干预措施：
  • 将npm install/pip install移至Dockerfile（可缓存）
  • 使用mcr.microsoft.com/devcontainers/*基础镜像
  • 为团队仓库配置预构建
  • 运行
    scripts/analyze-devcontainer.ts

DV2: Configuration Problems

DV2：配置问题

Symptoms: JSON errors, VS Code won't connect, features conflicting
Checklist:
  • devcontainer.json passes JSON validation
  • Using only ONE of: image, build.dockerfile, dockerComposeFile
  • Features are compatible and ordered correctly
  • Extensions use correct publisher.extension-name format
症状： JSON错误、VS Code无法连接、功能冲突
检查清单：
  • devcontainer.json通过JSON验证
  • 仅使用以下选项之一：image、build.dockerfile、dockerComposeFile
  • 功能兼容且顺序正确
  • 扩展使用正确的publisher.extension-name格式

DV3: Environment Parity Issues

DV3：环境一致性问题

Symptoms: Works in VS Code, fails in Codespaces (or vice versa)
Common Issues:
IssueLocal VS CodeCodespaces
Docker socketUsually availableDocker-in-Docker needed
Secrets.env files workUse Codespaces secrets
File watchingNativeMay need polling
症状： 在VS Code中可用，但在Codespaces中失败（反之亦然）
常见问题：
问题本地VS CodeCodespaces
Docker套接字通常可用需要Docker-in-Docker
密钥.env文件可正常使用使用Codespaces密钥
文件监听原生支持可能需要轮询

DV4: Multi-Service Complexity

DV4：多服务复杂性

Symptoms: Need database/cache/queue, services can't communicate
Interventions:
  • Use Docker Compose integration
  • Named volumes for persistence
  • Health checks for service readiness
  • Use 
    assets/devcontainer-compose.md
    template
症状： 需要数据库/缓存/队列、服务之间无法通信
干预措施：
  • 使用Docker Compose集成
  • 命名卷用于持久化
  • 服务就绪性健康检查
  • 使用
    assets/devcontainer-compose.md
    模板

DV5: Dockerfile Issues

DV5：Dockerfile问题

Symptoms: Build failures, huge images, no caching
Best Practices:
dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu
症状： 构建失败、镜像过大、无缓存
最佳实践：
dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu

Dependencies first (cached)

先安装依赖（可缓存）

RUN apt-get update && apt-get install -y
build-essential && rm -rf /var/lib/apt/lists/*
RUN apt-get update && apt-get install -y
build-essential && rm -rf /var/lib/apt/lists/*

Copy deps then install (cached if deps unchanged)

复制依赖文件后安装（依赖未变更时可缓存）

COPY package*.json ./ RUN npm install
COPY package*.json ./ RUN npm install

Code last (changes frequently)

最后复制代码（经常变更）

COPY . .
undefined
COPY . .
undefined

DV6: Devcontainer Validated

DV6：Devcontainer已验证

Indicators:
  • Startup under 2 minutes
  • Works in VS Code and Codespaces
  • New developers productive in 30 minutes
指标：
  • 启动时间少于2分钟
  • 在VS Code和Codespaces中均可正常使用
  • 新开发者可在30分钟内投入工作

Available Scripts

可用脚本

ScriptPurposeUsage
analyze-devcontainer.ts
Find issues and optimizations
deno run --allow-read scripts/analyze-devcontainer.ts
validate-dockerfile.ts
Check Dockerfile best practices
deno run --allow-read scripts/validate-dockerfile.ts
scan-image.ts
Vulnerability scanning (wraps Trivy)
deno run --allow-run scripts/scan-image.ts [image]
脚本用途使用方法
analyze-devcontainer.ts
查找问题并提供优化建议
deno run --allow-read scripts/analyze-devcontainer.ts
validate-dockerfile.ts
检查Dockerfile最佳实践
deno run --allow-read scripts/validate-dockerfile.ts
scan-image.ts
漏洞扫描（基于Trivy）
deno run --allow-run scripts/scan-image.ts [image]

Anti-Patterns

反模式

The Kitchen Sink

大杂烩式配置

Installing every tool "just in case" - 10+ minute startups. Fix: Start minimal. Add only when needed.
安装所有“可能用到”的工具——导致启动时间超过10分钟。 修复方案： 从最小配置开始，仅在需要时添加工具。

The postCreateCommand Overload

postCreateCommand过载

Everything in postCreateCommand - runs every time. Fix: Move stable operations to Dockerfile.
所有操作都放在postCreateCommand中——每次启动都会运行。 修复方案： 将稳定的操作移至Dockerfile。

The Snowflake Container

雪花式容器

Manual changes inside running containers. Fix: ALL changes go in config files.
在运行中的容器内进行手动更改。 修复方案： 所有变更都要写入配置文件。

Templates

模板

  • assets/devcontainer-simple.md
    - Basic single-container setup
  • assets/devcontainer-dockerfile.md
    - Custom Dockerfile approach
  • assets/devcontainer-compose.md
    - Multi-service setup
  • assets/devcontainer-simple.md
    - 基础单容器搭建模板
  • assets/devcontainer-dockerfile.md
    - 自定义Dockerfile方案模板
  • assets/devcontainer-compose.md
    - 多服务搭建模板

Related Skills

相关技能

  • system-design - Multi-service architecture informs Compose config
  • pwa-development - Consistent environment for PWA toolchain
  • system-design - 多服务架构为Compose配置提供参考
  • pwa-development - 为PWA工具链提供一致的环境