Dev Containers 的核心是通过 devcontainer.json 精确控制容器生命周期、挂载路径与用户权限，而非简单复用 Dockerfile 或 docker-compose.yml；必须显式指定 dockerComposeFile 路径（相对于 .devcontainer/）、service 名称（大小写敏感），统一 workspaceFolder 与 volumes 映射路径，设 command: sleep infinity 保持容器运行，并配置 remoteUser 或 USER node 解决 npm 权限问题，且需手动重建容器以生效配置变更。
Dev Containers 不是“把 Node 装进 Docker 就完事”，而是用 devcontainer.json 控制容器生命周期、挂载行为和开发体验。直接复用 Dockerfile 或硬写 docker-compose.yml 容易卡在端口不通、文件同步失败、npm install 权限报错这些地方。
devcontainer.json 必须显式声明 service 和 dockerComposeFile
VSCode 不会自动识别项目根目录下的 docker-compose.yml。如果你用多服务（比如 Node + PostgreSQL），必须在 .devcontainer/devcontainer.json 里明确指定：
-
"dockerComposeFile": "docker-compose.yml"—— 路径是相对于.devcontainer/的，不是项目根目录 -
"service": "app"—— 必须和docker-compose.yml中的 service 名完全一致，大小写敏感 - 不要同时写
"image"和"dockerComposeFile"，VSCode 会报错：「conflicting configuration」
volume 挂载路径必须匹配 workspaceFolder
默认挂载行为是把当前工作区映射到容器内 /workspaces/<folder-name>，但如果你在 devcontainer.json 里写了 "workspaceFolder": "/workspace"，而 docker-compose.yml 里写的是 volumes: - .:/workspace，实际效果是 host 的项目根目录 → 容器的 /workspace。但 VSCode 的终端和调试器仍会以 /workspaces/<folder-name> 为默认工作路径，导致 npm run dev 找不到 package.json。
正确做法是统一路径：
- 要么删掉
devcontainer.json中的workspaceFolder字段，让 VSCode 自动推导 - 要么在
docker-compose.yml的 service 下加working_dir: /workspace，并确保 volume 映射目标一致 - 别用
../src:/workspace/src这类相对路径——Docker Compose 解析时依赖上下文，容易挂载空目录
Node 启动后立即退出？加 command: sleep infinity
Dev Containers 本质是远程开发会话，不是跑应用的服务容器。如果 docker-compose.yml 里 app 服务的 command 是 npm start，容器启动即执行完就退出，VSCode 连不上。
必须让容器保持运行：
- 开发阶段用
command: sleep infinity—— 简单可靠，VSCode 连上后再手动启服务 - 或者用
command: tail -f /dev/null，语义更清晰 - 别依赖
CMD ["npm", "start"]在Dockerfile里——它会被docker-compose.yml的command覆盖，且无法交互
npm install 权限被拒？别在 container 内用 root 跑 npm
Node 官方镜像默认以 root 用户启动，但 npm install 在非 root 下才安全。常见错误是：npm WARN checkPermissions Missing write access to /workspace/node_modules。
解决方式只有两个有效路径：
- 在
Dockerfile里加USER node（注意顺序：必须在WORKDIR和COPY之后，RUN npm install之前） - 或在
devcontainer.json里加"remoteUser": "node"，强制 VSCode 终端以该用户登录 - 别试图用
chown -R node:node /workspace—— 挂载卷权限由 host 决定，容器内改无效
真正麻烦的从来不是“能不能跑起来”，而是“为什么改了配置没生效”。VSCode Dev Containers 的缓存机制很隐蔽：Reopen in Container 不会自动 rebuild，要手动触发 Dev Containers: Rebuild Container；devcontainer.json 改了字段但没重启会话，旧配置还在内存里。最省事的验证方式：删掉 .devcontainer/.devcontainer-cache 目录再试。
