根本原因是N-API ABI版本不匹配：系统Node（如v20.x，napi=8）重建的原生模块无法被VS Code内置Node（v22.4.0，napi_build_version=9）加载；需用--napi-build-version=9 --runtime=electron --target=34.0.0重编译，并清空node_modules/.pnpm和out/缓存。
VSCode调试时提示“Cannot find module './build/Release/xxx.node'”
这不是路径写错，而是 N-API ABI 版本不匹配——你本地 npm rebuild 生成的 .node 文件，用的是系统 Node 的 napi_build_version（比如 v20.x → napi=8），但 VS Code 插件主机运行在 Electron 内置 Node 上（v22.4.0 → napi_build_version=9），两者不兼容，加载直接失败。
- 验证方式：在插件输出通道或调试控制台执行
process.versions.napi，看输出是8还是9 - 别信
node -v输出，它只反映终端里那个 Node，和插件实际运行环境无关 - 重编译必须带三参数：
--napi-build-version=9 --runtime=electron --target=34.0.0（对应 VS Code 1.90+） - 务必先清空插件目录下的
node_modules/.pnpm和out/，否则旧二进制会被缓存优先加载
launch.json 中 runtimeExecutable 设了还是报错
runtimeExecutable 只影响调试会话的主进程，对插件主机（Extension Host）完全无效。也就是说，你设了 "runtimeExecutable": "${env:NVM_BIN}/node"，断点能停、program 能跑，但只要插件用了原生模块（比如 sqlite3、sharp、ffi-napi），它仍会去加载 VS Code 自带 Node 对应的 ABI。
- 硬编码路径（如
/Users/xxx/.nvm/versions/node/v18.17.0/bin/node）没用，改了也救不了插件 - 想让插件正常工作，唯一办法是让它编译时就匹配
process.versions.napi值，而不是调试器用哪个 Node - 如果项目必须用 v20.x 开发，又依赖原生模块，建议用 Dev Containers 隔离：选
node:20镜像，容器内npm rebuild生成的二进制天然匹配容器 Node，且不影响宿主机 VS Code
Windows 下 node.exe 路径含中文或空格导致加载失败
报错信息里出现乱码路径（如 d:///nodejs/node.exe）或 spawn node ENOENT，基本可锁定为安装路径含中文或空格，Windows 系统调用时未正确转义。
- 不要用
C:\Program Files\nodejs\node.exe这类路径填runtimeExecutable，即使加双引号也可能失效 - 推荐重装 Node.js 到无空格无中文路径，例如
C:\nodejs\或D:\nvm\nodejs\ - nvm-windows 用户请确认
nvm root输出路径不含中文，否则nvm use后NVM_BIN也会污染 - 验证：在 VS Code 终端运行
echo %NVM_BIN%，再手动执行该路径下node.exe -v
Dev Container 是唯一稳解跨版本原生模块冲突的方案
当项目间 Node 版本差跨大版本（如 v14 ↔ v22）、或必须同时开发多个 ABI 不兼容的模块时，全局 nvm use 或反复 npm rebuild 都是临时止痛药。真正隔离运行时 ABI 的只有容器。
- 安装 Dev Containers 插件，打开项目后点击左下角 >
Reopen in Container - 选择 Node.js 模板时直接指定镜像标签，如
node:20-bullseye或node:22-bookworm - 容器启动后，
which node和process.versions.napi一定一致，且所有npm install生成的原生模块都自动适配 - 宿主机 VS Code 版本升级（比如从 1.89 升到 1.90）不会影响容器内环境，
napi_build_version锁死在镜像定义里
最易被忽略的一点：ABI 兼容性不是“Node 版本够新就行”，而是 process.versions.napi 必须与二进制编译时声明的 napi_build_version 完全相等——差 1 都不行，且无法降级兼容。
