优先选用mcr.microsoft.com/vscode/devcontainers/javascript-node:18镜像，它预装npm、yarn、nvm、git并配置非root用户权限；避免使用node:latest或node:alpine，以防调试器缺失、native模块崩溃及环境不一致。
devcontainer.json 里 image 字段选哪个 Node 镜像
别直接写 node:latest——它不带调试器、没预装常用 CLI 工具，且版本漂移会导致团队环境不一致。优先用微软官方维护的 mcr.microsoft.com/vscode/devcontainers/javascript-node 镜像，后面跟上明确版本号，比如 18 或 20。
常见错误是复制网上旧教程里的 node:alpine，结果发现 npm install 报 ENOTDIR 或调试时断点不命中——Alpine 缺少 glibc，某些 native 模块（如 bcrypt、sharp）根本跑不起来。
-
mcr.microsoft.com/vscode/devcontainers/javascript-node:18：带完整 npm、yarn、nvm、git，已配置好非 root 用户权限 - 若项目必须用 Node 20，改用
:20；但注意 TypeScript 5.0+ 才完全支持 Node 20 的 ES 模块解析 - 避免混用镜像来源：不要在同一个
devcontainer.json里既引用微软镜像又自己写Dockerfile，除非你清楚构建上下文和 layer 缓存机制
launch.json 中 sourceMap 和 port 怎么配才不白忙
VSCode 容器调试失败，八成出在 launch.json 的这两个字段。关键不是“开了 sourceMap”，而是它是否匹配实际输出路径。
如果你用 tsc --outDir dist，但没在 tsconfig.json 里设 "sourceMap": true 和 "inlineSources": true，那 sourceMap: true 在 launch.json 里就是摆设。Node 进程根本读不到映射关系。
-
port必须和应用实际监听端口一致，比如 Express 启动时写app.listen(3000)，这里就得填3000，不是8080或3001 -
sourceMap设为true后，还要确认outFiles字段指向正确路径，例如"outFiles": ["./dist/**/*.js"] - 如果用 ESM（
"type": "module"），确保package.json有该字段，否则 VSCode 仍按 CommonJS 解析，import路径错乱导致断点失效
容器内 node_modules 是挂载还是重建
本地 node_modules 直接挂进容器？危险操作。不同系统 ABI、不同 Node 版本编译的 native 模块（如 sqlite3、fsevents）会崩溃或报 MODULE_NOT_FOUND。
正确做法是：把 package.json 和 package-lock.json 挂进去，在容器内运行 npm ci 或 yarn install，让依赖在目标环境中原生构建。
- 在
devcontainer.json的postCreateCommand里写"npm ci"，而不是"npm install"——前者严格按 lock 文件还原，避免意外升级 - 用
mounts挂载 npm 缓存卷（如"source": "npm-cache", "target": "/root/.npm"），加速重复安装 - 别忽略
.dockerignore：务必排除node_modules、dist、.git，否则构建镜像时体积暴增且缓存失效
为什么 Reopen in Container 后终端里 node -v 是对的，但调试器连不上
最常被忽略的一点：容器启动后，VSCode 并未自动激活 Node.js 调试扩展。它只装了 UI 层插件，没在容器内部署语言服务器。
检查 devcontainer.json 的 customizations.vscode.extensions 数组，必须包含 "ms-vscode.vscode-typescript-next"（TypeScript 项目）或 "dbaeumer.vscode-eslint"（ESLint 支持），但最关键的是 "ms-vscode.node-debug" ——这个包负责注入调试适配器。
- 如果用了 TypeScript，
extensions里漏掉"ms-vscode.vscode-typescript-next"，编辑器无法解析import语法，断点标红但不生效 - 执行
Remote-Containers: Show Log命令，看日志里有没有Failed to launch debug adapter或Cannot find module 'vscode-debugadapter' - 重启容器前，先删掉
.devcontainer/.vscode-server目录——旧版 server 进程残留常导致调试通道静默失败
package.json 里少了个 "type": "module"，都可能让断点永远停在 require 那行不动。 
