article-8-devcontainer-clean.md

用 DevContainer 一键搭建 AI 开发环境：VS Code + Python + GPU + Jupyter 全配置

做 AI 开发的读者都经历过「环境地狱」：CUDA 版本不对、Python 依赖冲突、不同项目需要不同的工具链……DevContainer（开发容器）正是解决这个问题的利器。

本教程教你用 VS Code 的 DevContainer 功能，一键创建标准化的 AI 开发环境。

### 什么是 DevContainer？

DevContainer 是 VS Code 的一个扩展功能，它利用 Docker 容器来定义开发环境。你只需要在项目中放一个配置文件，任何打开这个项目的人都能获得完全一致的开发环境——Python 版本、依赖库、VS Code 插件，全都自动安装。

### 第一步：安装前置工具

# 安装 Docker（Ubuntu/Debian）
sudo apt update && sudo apt install docker.io -y
sudo usermod -aG docker $USER

# 安装 VS Code 扩展
# 在 VS Code 中搜索并安装「Dev Containers」扩展

### 第二步：创建配置文件

在项目根目录创建 `.devcontainer/devcontainer.json`：

{
  "name": "AI Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  "features": {
    "ghcr.io/devcontainers/features/nvidia-cuda:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-toolsai.jupyter",
        "github.copilot",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python"
      }
    }
  },
  "postCreateCommand": "pip install torch torchvision jupyter numpy pandas matplotlib transformers",
  "runArgs": ["--gpus", "all"]
}

### 第三步：启动环境

在 VS Code 中按 `F1`，输入「Dev Containers: Reopen in Container」，选择配置文件。VS Code 会自动：

1. 拉取 Python 3.12 镜像

2. 安装 CUDA 支持

3. 自动安装 PyTorch、Jupyter 等依赖

4. 加载你指定的 VS Code 扩展

整个过程首次约 3-5 分钟，之后秒级启动。

### 第四步：验证环境

打开终端，确认一切就绪：

python -c "import torch; print(f'PyTorch {torch.__version__}, CUDA: {torch.cuda.is_available()}')"
# 输出: PyTorch 2.x.x, CUDA: True

打开任意 `.ipynb` 文件，Jupyter 内核自动可用。现在你可以在这个完全隔离的容器中做任何 AI 开发实验，不会影响宿主机的系统环境。

### 团队协作的价值

把 `.devcontainer` 目录提交到 Git 仓库后，团队中的任何人都能用完全相同的环境运行你的代码。告别「在我机器上能跑」的经典问题。

**最佳实践：** DevContainer 不仅省去了手动配置环境的烦恼，更重要的是实现了「环境即代码」——开发环境可以版本管理、可以代码审查、可以持续集成。

常见踩坑与解决方案

新手使用 DevContainer 时最常遇到的问题：

1. 「Docker not running」：DevContainer 依赖 Docker 运行。安装 Docker 后别忘了执行 `sudo usermod -aG docker $USER` 并注销重新登录，否则 VS Code 可能找不到 Docker 守护进程。

2. GPU 不可用：容器内 `nvidia-smi` 无输出。需要确保宿主机已安装 NVIDIA Container Toolkit：`sudo apt install nvidia-container-toolkit -y && sudo systemctl restart docker`。安装后再重建容器即可。

3. postCreateCommand 失败：如果 `pip install` 因网络问题超时，可以在 `devcontainer.json` 中配置国内镜像源：在 `postCreateCommand` 中加入 `-i https://pypi.tuna.tsinghua.edu.cn/simple`。

4. 磁盘空间不足：DevContainer 的镜像和缓存会占用不少空间。定期执行 `docker system prune -a` 清理未使用的镜像和卷，但注意这会删除非运行中的容器数据。

进阶配置推荐

如果你做深度学习训练，可以在配置文件中挂载数据目录，避免每次重建容器都重新下载数据集：

"mounts": [
  "source=/path/to/your/datasets,target=/workspace/datasets,type=bind"
]

DevContainer + GitHub Codespaces 的组合拳

如果你的团队使用 GitHub，还可以利用 Codespaces 直接在云端启动 DevContainer 环境——完全不需要本地安装 Docker 或 GPU。团队成员只需在浏览器中打开仓库，点击「Code」→「Codespaces」→「Create codespace」，几分钟后就能获得一个和本地完全一致的开发环境。这对硬件参差不齐的团队来说尤其有价值——用 MacBook Air 的人也可以直接使用云端 GPU 跑模型训练。

对于个人开发者来说，GitHub Codespaces 每月提供 60 小时免费额度，足够日常学习和实验使用。配合 DevContainer 的配置，可以实现「在任何设备上打开浏览器就能写代码跑模型」的极致体验。

— END —
LC 智趣厅 · 科技与生活的交点
ihygg.cn