devcontainer.json 是 vscode 用于定义开发容器环境的配置文件，它指定镜像、用户、工作区路径、扩展等，使开发环境在容器中一致隔离运行。
devcontainer.json 是什么，它在 VSCode 里起什么作用
devcontainer.json 不是启动容器的脚本，也不是 Docker Compose 替代品，它是 VSCode 用来定义「开发容器环境」的配置文件。VSCode 读取它后，会拉起一个带预装工具链、特定用户权限、挂载路径和端口转发规则的容器，并把编辑器完全运行在这个隔离环境里——你写的代码、运行的命令、调试的进程，全在容器中发生。
它解决的核心问题是：让不同开发者、CI 环境、甚至不同操作系统上的 VSCode 行为一致。不是“用 Docker 跑服务”，而是“把整个开发桌面搬进容器”。
最简可用的 devcontainer.json 配置长什么样
从零开始写 devcontainer.json 容易掉坑里，比如漏掉 remoteUser 导致权限错误，或没设 workspaceFolder 让代码不自动挂载。下面是一个能立刻跑起来的最小配置（基于官方 mcr.microsoft.com/devcontainers/python:3.11 镜像）：
{
"image": "mcr.microsoft.com/devcontainers/python:3.11",
"remoteUser": "vscode",
"workspaceFolder": "/workspace",
"customizations": {
"vscode": {
"extensions": ["ms-python.python"]
}
}
}
关键点说明：
-
image必须指向可拉取的镜像；本地构建的镜像要用build字段配dockerfile，不能直接写image: myapp-dev -
remoteUser推荐显式设为vscode（该用户已预建好家目录和 sudo 权限），否则默认是root，很多扩展（如 Python 的 Pylance）会拒绝加载 -
workspaceFolder必须与容器内实际挂载路径一致；VSCode 默认把当前文件夹挂到/workspace，所以这里不能写成/src或留空 -
extensions列表只影响容器内 VSCode Server，主机上装的插件不会自动同步过去
常见报错和对应修复方式
打开文件夹后点击 “Reopen in Container”，卡住或报错是最常遇到的问题。几个高频错误和解法：
- 报错
Command failed: docker build ... The command '/bin/sh -c apt-get update' returned a non-zero code: 100→ 镜像构建阶段网络失败。在devcontainer.json里加"runArgs": ["--network=host"]，或改用国内镜像源（需自建 Dockerfile） - 终端一打开就显示
bash: /usr/bin/bash: No such file or directory→ 基础镜像没装 shell。换用带完整工具链的镜像（如python:3.11-slim不行，得用python:3.11或devcontainers/python） - Python 扩展提示 “No interpreter selected”，
python.defaultInterpreterPath显示为空 → 在devcontainer.json的customizations.vscode.settings里补上："python.defaultInterpreterPath": "/usr/local/bin/python" - 容器起来后端口没暴露，
localhost:8000访问不到 Flask 应用 → 加"forwardPorts": [8000]，且确保应用绑定的是0.0.0.0:8000而非127.0.0.1:8000
什么时候该用 Dockerfile 而不是 image 字段
当你需要安装私有包、复制本地配置、或复用现有构建流程时，image 字段就不够用了。此时必须切到 build 模式：
{
"build": {
"dockerfile": "./Dockerfile",
"context": ".."
},
"remoteUser": "vscode",
"workspaceFolder": "/workspace"
}
注意两个易错点：
-
context是docker build的上下文路径，不是Dockerfile路径；如果Dockerfile在.devcontainer/Dockerfile，而项目根目录有requirements.txt，那context得设为".."，否则COPY requirements.txt会失败 - 不要在
Dockerfile里写CMD或ENTRYPOINT—— dev container 启动后要交还控制权给 VSCode，否则容器立即退出 - 如果依赖 Git 仓库私有子模块，记得在
Dockerfile中提前配置 SSH agent 转发或 token 注入，否则git clone会卡住
真正麻烦的从来不是写配置，而是搞清哪一步在容器里执行、哪一步在宿主机执行、哪一步由 VSCode 自己接管——比如端口转发是 VSCode 做的，docker run -p 是无效的；又比如 postCreateCommand 运行在容器启动后、VSCode 连接前，适合做 pip install，但不适合跑长期服务。
