Docker扩展在VSCode中仅提供可视化界面，依赖本地Docker Engine和CLI；需确保docker命令可达、权限正确、手动刷新列表，并注意构建上下文、多阶段Dockerfile及Dev Container配置路径与网络问题。
Docker 扩展在 VSCode 中不直接“集成”容器运行时，它只是个可视化操作界面；真正起作用的是你本地已安装并运行的 Docker Engine。
确认 Docker CLI 可被 VSCode 正确调用
VSCode 的 Docker 扩展依赖系统 PATH 中的 docker 命令。如果扩展显示 “Docker is not reachable” 或列表为空，大概率是 CLI 不可达：
- 终端中执行
docker version必须成功返回客户端和服务端版本（服务端部分不能为 “Cannot connect…”） - Windows 用户若用 WSL2 后端，需确保 Docker Desktop 已启动且设置了 “Use the WSL 2 based engine”
- macOS 上通过 Homebrew 安装的 Docker Desktop，有时需重启 VSCode 才能读取更新后的 PATH
- Linux 用户注意：普通用户需加入
docker用户组，并登出重进，否则会报Permission denied while trying to connect to the Docker daemon socket
在 VSCode 中正确查看和操作容器/镜像
扩展本身不自动刷新状态，很多“看不到容器”问题其实是没手动触发刷新：
- 侧边栏 Docker 图标点击后，展开的节点（如
Containers、Images）右键有Refresh选项，或按F5键 - 新启动的容器不会实时出现在列表里，必须手动刷新；后台静默运行的容器（如
docker run -d）也一样 - 若只看到
docker-compose.yml但无服务实例，检查是否已执行过docker compose up（注意不是docker-compose，V2 命令名已统一） - 扩展默认只显示正在运行的容器；要查看已停止的，右键
Containers→Toggle Show All Containers
从 VSCode 直接构建并运行多阶段 Dockerfile
扩展支持一键构建和运行，但对多阶段构建或自定义上下文路径容易出错：
- 右键
Dockerfile→Build Image…会弹出输入框，默认 tag 是latest；建议输全称如myapp:dev，避免覆盖 - 若
Dockerfile不在工作区根目录，VSCode 仍会以工作区根为构建上下文（.），可能导致COPY失败；此时应先在终端用docker build -f path/to/Dockerfile -t myapp .验证 - 右键
Dockerfile→Run Interactive…实际执行的是docker run -it --rm <image>，不带端口映射或卷挂载；生产调试请改用docker run命令或写devcontainer.json - 构建过程日志在 VSCode 的
Output面板中选择Docker通道查看，错误通常比弹窗提示更具体
Dev Container 连接失败的常见断点
用 .devcontainer/devcontainer.json 重开窗口时卡在 “Starting Dev Container”，问题往往不在配置本身：
- 检查
image或build字段指定的镜像是否存在：docker images | grep your-image-name - 若使用
build，确保dockerfile路径相对于devcontainer.json是正确的（不是工作区根） - Windows + WSL2 组合下，若工作区在 Windows 文件系统（
/mnt/c/...），构建可能因文件权限或性能问题失败；建议把代码放在 WSL2 的 Linux 文件系统内（如~/project） - 首次构建时 VSCode 会拉取基础镜像，网络慢会导致超时；可提前在终端运行
docker pull mcr.microsoft.com/vscode/devcontainers/base:ubuntu等常用镜像
真正的难点从来不是点几下鼠标，而是搞清 Docker 扩展背后调用的是哪条命令、当前上下文在哪、权限有没有漏掉——这些信息不会出现在 UI 提示里，得看终端输出和 docker info 输出。
