devcontainer.json 是 VSCode 定义开发容器环境的配置文件，指定镜像、扩展、端口等，实现隔离、可复现的 Python 开发环境；必须正确配置 image、customizations.vscode.extensions 和 forwardPorts 三个字段，缺一不可。
直接用 devcontainer.json 指定镜像 + 安装扩展 + 转发端口，就能在 VS Code 里跑起一个隔离、可复现、带完整 Python 工具链的容器环境。不需要手动装 Python、pip、venv 或配置 PATH。
devcontainer.json 必须填对的三个字段
这个文件是 Dev Container 的“启动说明书”，少一个关键字段就进不了容器，或者进去后缺东西。
-
"image"：必须指向一个可用的 Python 基础镜像，比如"mcr.microsoft.com/devcontainers/python:3.11"（微软官方维护，更新勤、兼容好）。别用python:3.11-slim这类通用镜像——它没预装git、curl、build-essential，后续装包或调试会卡在command not found -
"customizations.vscode.extensions"：写死你项目真正依赖的扩展，例如"ms-python.python"和"ms-python.pylance"。不加这个，容器里打开 .py 文件就是纯文本，没有语法高亮、跳转、补全 -
"forwardPorts"：如果你的 Python 服务要跑 Web（如 FastAPI、Flask），必须显式列出端口，例如[8000, 8080]。VS Code 不会自动猜——不写，浏览器访问localhost:8000就是连接被拒绝
GPU 支持不是默认开启的
很多 Python 项目（比如清音刻墨、Audio Pixel Studio）依赖 CUDA 加速，但 Docker 默认不暴露 GPU 设备。光靠 "image" 指向含 cuda 的镜像还不够。
- Linux 用户：确保已安装
nvidia-container-toolkit，并在devcontainer.json中加"runArgs": ["--gpus", "all"] - Windows/macOS 用户：Docker Desktop 需在设置里勾选 “Use the WSL 2 based engine”（Win）或 “Enable GPU support”（macOS Sonoma+），否则
--gpus all会被静默忽略 - 验证是否生效：进容器后运行
nvidia-smi。如果报错或没输出，说明 GPU 没挂载成功，PyTorch/TensorFlow 会 fallback 到 CPU，速度差 5–10 倍
常见报错和绕过方法
实际操作中，90% 的失败都卡在这几个地方，而不是配置逻辑本身。
立即学习“Python免费学习笔记（深入）”；
-
"The container failed to start: exit code 1"：大概率是devcontainer.json里用了不存在的镜像名，或镜像拉取失败。先在终端手动执行docker pull mcr.microsoft.com/devcontainers/python:3.11看是否成功 -
"Command 'Dev Containers: Reopen in Container' not found"：Remote - Containers 扩展没启用，或安装后没重启 VS Code。检查扩展面板里ms-vscode-remote.remote-containers是否状态为 “Enabled” - 容器启动后，Python 解释器显示为
Python 3.11.9 ('system')，但实际不在容器内：说明工作区没在项目根目录打开。必须用 VS Code 打开包含.devcontainer/的那个文件夹，不能只打开某个 .py 文件
最易被忽略的一点：每次改完 devcontainer.json，必须重新触发 Dev Containers: Reopen in Container，而不是 reload window。后者不会重建容器，改了的 runArgs 或 features 一条都不会生效。
