VS Code Dev Containers 完全指南：从入门到精通

什么是 Dev Containers？

VS Code Dev Containers（开发容器）是一种让您能够在容器中使用代码库的开发工具。它允许您：

隔离开发环境：每个项目都有独立、一致的开发环境
消除环境配置问题：不再需要手动安装依赖和工具
跨平台一致性：团队成员使用相同的容器配置，确保环境一致
快速切换项目：在不同项目间切换时无需重新配置环境

核心优势

“一次配置，处处运行”

Dev Containers 基于 Docker 技术，但您不需要深入了解 Docker 也能使用它。VS Code 提供了友好的界面和预设配置，让容器化开发变得简单。

架构概览

  flowchart TB
    A[VS Code] --> B[Dev Container Extension]
    B --> C[Docker Engine]
    C --> D[Dev Container]
    D --> E[开发环境]
    E --> F[源代码]
    E --> G[工具和扩展]
    E --> H[运行时依赖]

    style A fill:#007acc,color:#fff
    style B fill:#6c757d,color:#fff
    style C fill:#2496ed,color:#fff
    style D fill:#6db33f,color:#fff
    style E fill:#e67e22,color:#fff

典型使用场景

团队协作：新成员只需克隆代码并打开 Dev Container，即可立即开始开发
多版本测试：在不同版本的 Node.js、Python 等环境中测试代码
微服务开发：同时运行多个服务容器，每个服务独立开发
学习新技术：在隔离环境中尝试新技术栈，不影响宿主机

快速上手

前置要求

安装 Docker Desktop
安装 VS Code
- 下载 VS Code
安装 Dev Container 扩展
- 在 VS Code 扩展市场搜索 “Dev Containers”
- 或直接访问 Dev Containers 扩展页面

使用预定义容器

最简单的方式是使用 Microsoft 提供的预定义容器配置：

打开 VS Code
使用 Ctrl+Shift+P（或 Cmd+Shift+P）打开命令面板
输入 “Dev Containers: Add Dev Container Configuration Files…”
选择您需要的开发环境（如 Node.js、Python、Java 等）
VS Code 会自动创建 .devcontainer 目录和配置文件

初次体验

视频展示了如何快速创建和使用您的第一个 Dev Container。即使您没有 Docker 经验，也能在几分钟内启动完整的开发环境。

工作流程

  sequenceDiagram
    participant User as 开发者
    participant VSCode as VS Code
    participant Docker as Docker
    participant Container as 容器

    User->>VSCode: 打开项目文件夹
    VSCode->>Docker: 请求创建容器
    Docker->>Container: 启动容器
    Container->>VSCode: 连接就绪
    VSCode->>User: 显示开发环境
    User->>VSCode: 开始编码

自定义配置

理解 devcontainer.json

.devcontainer/devcontainer.json 是 Dev Containers 的核心配置文件，定义了容器的行为和配置。

基本结构示例

{
  "name": "My Node.js Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
    }
  },
  "postCreateCommand": "npm install",
  "forwardPorts": [3000],
  "remoteUser": "vscode"
}

关键配置项说明

配置项	说明	示例
`name`	容器显示名称	`"My Project"`
`image`	基础镜像	`"mcr.microsoft.com/devcontainers/base:ubuntu"`
`build.dockerfile`	自定义 Dockerfile 路径	`"Dockerfile"`
`features`	Dev Containers Features	See below
`customizations`	VS Code 扩展和设置	See below
`postCreateCommand`	容器创建后执行的命令	`"npm install"`
`forwardPorts`	自动转发的端口	`[3000, 8080]`
`mounts`	挂载卷	`["source=${localWorkspaceFolder}/../data,target=/data"]`

使用 Dockerfile

当预定义镜像无法满足需求时，可以使用自定义 Dockerfile：

FROM mcr.microsoft.com/devcontainers/base:ubuntu

# 安装 Node.js
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install --no-install-recommends nodejs npm

# 安装额外的工具
RUN apt-get install -y git curl vim

# 设置默认工作目录
WORKDIR /workspace

# 切换到非 root 用户
USER vscode

对应的 devcontainer.json：

{
  "name": "My Custom Container",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python"]
    }
  }
}

使用自定义 Dockerfile 时，确保安装了 sudo 并创建了 vscode 用户，否则 Dev Container 扩展可能无法正常工作。

Docker Compose 集成

对于需要多个容器的复杂应用（如前端 + 后端 + 数据库），使用 Docker Compose：

docker-compose.yml:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ../..:/workspaces:cached
    command: sleep infinity
    network_mode: service:db

  db:
    image: postgres:15
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: development

volumes:
  postgres-data:

.devcontainer/devcontainer.json:

{
  "name": "Multi-Container Project",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}"
}

使用 Features

Dev Containers Features 是可重用的配置单元，简化了常见工具的安装：

{
  "name": "Full-Stack Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "lts"
    },
    "ghcr.io/devcontainers/features/python:1": {
      "version": "latest"
    },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/git:1": {}
  }
}

浏览更多 Dev Containers Features 来发现可用的功能模块。

高级功能

多容器工作区

当您需要在多个容器中同时工作时（如微服务架构），可以创建多容器配置：

{
  "name": "Microservices Workspace",
  "dockerComposeFile": "docker-compose.yml",
  "service": "web",
  "workspaceFolder": "/workspace",
  "services": {
    "web": "Frontend Service",
    "api": "Backend API",
    "db": "Database"
  }
}

Dev Container 模板

使用社区贡献的 Dev Container 模板：

访问 containers.dev/templates
搜索您需要的模板（如 Python、Go、Rust 等）
一键添加到项目中

端口转发

自动或手动转发容器端口到宿主机：

{
  "forwardPorts": [3000, 8080, 5432],
  "portsAttributes": {
    "3000": {
      "label": "Application",
      "onAutoForward": "notify"
    },
    "5432": {
      "label": "Database",
      "onAutoForward": "silent"
    }
  }
}

挂载卷

共享文件和目录：

{
  "mounts": [
    "source=${localWorkspaceFolder}/../data,target=/data,type=bind,consistency=cached",
    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
  ]
}

环境变量

设置容器环境变量：

{
  "containerEnv": {
    "NODE_ENV": "development",
    "API_ENDPOINT": "http://localhost:8080",
    "DEBUG": "myapp:*"
  },
  "remoteEnv": {
    "PATH": "${containerEnv:PATH}:/custom/bin"
  }
}

生命周期脚本

在不同阶段执行命令：

{
  "initializeCommand": "echo '初始化命令在宿主机运行'",
  "onCreateCommand": "echo '容器创建后运行'",
  "updateContentCommand": "echo '每次容器启动时运行'",
  "postCreateCommand": "npm install && npm run setup",
  "postStartCommand": "npm run dev",
  "postAttachCommand": "echo '连接到容器后运行'"
}

最佳实践与技巧

性能优化

使用卷缓存
- Linux/macOS: 使用 cached 或 delegated 选项
- Windows: 使用 WSL2 后端以提高性能

减少文件监听

{
  "settings": {
    "files.watcherExclude": {
      "**/node_modules/**": true,
      "**/dist/**": true
    }
  }
}

使用 .devcontainerignore
- 类似 .gitignore，避免复制不必要的文件到容器中
- 忽略 node_modules、dist、.git 等目录

常见问题排查

容器无法启动？

检查 Docker Desktop 是否运行

查看 VS Code 输出面板的 “Dev Containers” 日志

尝试重建容器：“Dev Containers: Rebuild Container”

端口无法访问？

检查防火墙设置

确认应用监听 0.0.0.0 而非 127.0.0.1

使用 “Dev Containers: Forward Port from Container” 手动转发

扩展无法安装？

检查网络连接

尝试在 customizations.vscode.extensions 中声明

"customizations": {
  "vscode": {
    "extensions": ["publisher.extension-name"]
  }
}

安全考虑

避免在镜像中存储敏感信息
使用非 root 用户运行容器（remoteUser 配置）
定期更新基础镜像
限制容器权限（不使用 --privileged）

团队协作建议

将 .devcontainer 提交到版本控制
- 确保所有团队成员使用相同的配置
编写详细的 README
- 说明如何使用 Dev Container
- 列出包含的工具和扩展
使用一致的 Node.js/Python 版本
- 在 devcontainer.json 中指定版本
- 使用 .nvmrc 或 requirements.txt 锁定版本

视频教程资源

英文教程

官方资源：

中文教程

Bilibili 视频av号或BV号错误！请检查视频av号或BV号是否正确

当前视频av或BV号：，视频分P：1

推荐视频：

VS Code 轻松使用 Docker 容器 - 基础入门
使用 VS Code 的 Remote Container 打造 Java 开发环境 - Java 实践
在宿主机编辑和运行 docker 内的 python 代码 - Python 开发

参考资源

官方文档

社区文章

工具与扩展

Dev Containers Features - 社区维护的 Features 集合
Dev Container Templates - 官方模板库

总结

VS Code Dev Containers 为现代开发提供了强大而灵活的环境管理方案：

✅ 一键启动：无需手动配置环境
✅ 一致性：团队成员使用相同的开发环境
✅ 隔离性：不影响宿主机环境
✅ 可移植性：配置文件可版本控制
✅ 灵活性：支持任意编程语言和工具

无论您是个人开发者还是团队成员，Dev Containers 都能显著提升开发效率和项目协作体验。

开始使用 Dev Containers，让开发环境配置成为历史！

最后更新：2026-01-12 相关标签：#vscode #devcontainers #docker #development #教程