devcontainer

Devcontainer 诊断

诊断 devcontainer 和 Docker 开发环境问题。帮助创建可复现、快速启动的开发环境，确保其在 VS Code、GitHub Codespaces 和团队成员之间保持一致。

何时使用此技能

在以下情况下使用此技能：

• 设置新的 devcontainer
• 容器启动过慢
• 配置错误或冲突
• VS Code 与 Codespaces 中的行为不同
• 需要多服务开发环境

在以下情况下不要使用此技能：

• 编写应用代码
• 部署到生产环境
• 配置 CI/CD 流水线

核心原则

开发容器应能让人立即投入工作。每项配置选择都会影响启动时间、可复现性和团队成员上手速度。请明确说明这些权衡。

诊断状态

DV0：没有 Devcontainer 策略

症状： 手动设置、“查看 README”，在一台机器上能用，在其他机器上却不行

应对措施：

• 从预构建的 devcontainer 基础映像开始
• 使用 assets/devcontainer-simple.md 模板

DV1：容器启动缓慢

症状： 启动耗时 5 分钟以上，postCreateCommand 负担过重，避免重建

关键问题：

• 实际启动需要多长时间？
• postCreateCommand 中有哪些内容？
• 是否在使用预构建？

应对措施：

• 将 npm install/pip install 移至 Dockerfile（可缓存）
• 使用 mcr.microsoft.com/devcontainers/* 基础映像
• 为团队仓库配置预构建
• 运行 scripts/analyze-devcontainer.ts

DV2：配置问题

症状： JSON 错误、VS Code 无法连接、功能冲突

检查清单：

• devcontainer.json 通过 JSON 验证
• 只使用以下选项之一：image、build.dockerfile、dockerComposeFile
• 功能彼此兼容且顺序正确
• 扩展采用正确的 publisher.extension-name 格式

DV3：环境一致性问题

症状： 在 VS Code 中能用，在 Codespaces 中失败（或反之）

常见问题：

问题	本地 VS Code	Codespaces
Docker socket	通常可用	需要 Docker-in-Docker
密钥	.env 文件可用	使用 Codespaces 密钥
文件监视	原生支持	可能需要轮询

DV4：多服务复杂性

症状： 需要数据库/缓存/队列，服务之间无法通信

应对措施：

• 使用 Docker Compose 集成
• 使用命名卷进行持久化
• 使用健康检查确认服务就绪
• 使用 assets/devcontainer-compose.md 模板

DV5：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/*

# Copy deps then install (cached if deps unchanged)
COPY package*.json ./
RUN npm install

# Code last (changes frequently)
COPY . .

DV6：Devcontainer 已验证

指标：

• 启动时间低于 2 分钟
• 在 VS Code 和 Codespaces 中均可运行
• 新开发者可在 30 分钟内投入工作

可用脚本

脚本	用途	用法
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]

反模式

大杂烩容器

“以防万一”安装所有工具——启动需要 10 分钟以上。 修复方法： 从精简配置开始。只在需要时添加。

postCreateCommand 负担过重

所有操作都放在 postCreateCommand 中——每次都会运行。 修复方法： 将稳定的操作移至 Dockerfile。

特例容器

在运行中的容器内手动修改。 修复方法： 所有更改都写入配置文件。

模板

• assets/devcontainer-simple.md - 基本的单容器设置
• assets/devcontainer-dockerfile.md - 自定义 Dockerfile 方案
• assets/devcontainer-compose.md - 多服务设置

相关技能

• system-design - 多服务架构会影响 Compose 配置
• pwa-development - 为 PWA 工具链提供一致的环境