构建上下文是docker build命令指定的路径，Docker客户端将该路径下所有文件打包发送至服务端，供Dockerfile中COPY、ADD等指令引用；默认为当前目录（.），但必须与Dockerfile中相对路径一致，否则导致文件找不到或复制错误。
docker build 是本地化编译的核心命令，VSCode 的 Docker 扩展只是它的图形化外壳。真正决定编译结果的，是你的 Dockerfile 内容、构建上下文路径和当前用户权限——不是点几下鼠标就能绕过这些。
构建前必须确认的三件事
VSCode 里右键 Build Image 失败，90% 情况下不是插件问题，而是底层环境没就绪：
-
docker version命令在 VSCode 集成终端中能正常输出客户端和服务端版本（服务端为server或dockerd） - 当前用户属于
docker用户组（Linux），或 Docker Desktop 以管理员身份运行（Windows/macOS）；否则会卡在permission denied while trying to connect to the Docker daemon socket - VSCode 本身没用
sudo启动（Linux/macOS），否则无法访问/var/run/docker.sock
缺一不可。插件不会帮你自动加 sudo，也不会替你改用户组。
Dockerfile 路径和构建上下文不匹配
右键 Dockerfile → Build Image 时，默认构建上下文是 .（项目根目录）。但如果你的 Dockerfile 在 ./docker/Dockerfile，而 COPY . /app 指令又在复制整个项目，那实际复制的是 ./docker/ 目录下的内容，不是你预期的源码根目录。
解决方法很简单：右键后弹出的输入框里，把构建上下文路径手动改成 ./docker（不是 ./docker/Dockerfile），镜像名填 myapp:local 即可。
常见错误现象：ERROR: failed to solve: failed to read dockerfile: open /var/lib/docker/tmp/buildkit-mount*/Dockerfile: no such file or directory —— 实际是上下文路径错，导致 Docker 守护进程找不到 Dockerfile。
多阶段构建必须显式指定 target
如果你的 Dockerfile 包含 FROM golang:1.21 AS builder 和 FROM alpine:3.19，默认 docker build 只构建最后一个 stage。VSCode 插件不会自动识别你想要构建 builder 阶段用于调试。
这时得用右键菜单里的 Build Image with Target，然后输入 builder（注意大小写和空格），等价于执行：
docker build --target builder -t myapp:builder .
不指定 --target 就直接 Build Image，插件永远只走最终 stage，调试时拿不到中间产物。
构建缓存失效却没意识到
VSCode 插件默认不带 --no-cache，也不显示每层缓存命中状态。你以为重新构建了，其实大部分 layer 都是复用的——这在 CI 环境是优点，在本地调试时却容易掩盖问题。
比如你改了 package.json 但没改 npm install 之前的 COPY 指令，缓存仍会复用旧的 node_modules。
临时验证是否真更新了？在集成终端里手动跑：
docker build --no-cache -t myapp:debug .
或者加 --progress=plain 看每一层是否 cached：
docker build --progress=plain -t myapp:debug .
图形界面里看不到这些细节，得切出去看。
本地化编译最易被忽略的一点：构建上下文是**路径**，不是“当前文件所在位置”；docker build 总是以该路径为 / 去解析所有相对路径（包括 COPY、ADD、WORKDIR）。哪怕你在 VSCode 里打开了子目录，只要上下文设错，COPY ../src 就会失败。 
