根本原因是Node.js运行时与C++扩展的ABI或构建环境不匹配，需用node-gyp按VSCode内置Node版本（如process.version查得）重建，并匹配平台工具链与STL/Glibc版本。
VSCode里require C++扩展报“Cannot find module”或“undefined symbol”
这不是路径写错，而是Node运行时与你编译的.node文件ABI不兼容。VSCode自带Node版本（比如process.version查到的是v18.18.2）和你本地node -v看到的很可能不同，node-gyp rebuild默认用的是系统Node，不是VSCode的。
- 在VSCode开发者工具控制台执行
process.version，记下真实版本号（如v20.15.0） - 用该版本重建：
node-gyp rebuild --target=20.15.0 --arch=x64 --dist-url=https://nodejs.org/download/release/ - Windows下确保MSVC工具链架构与VSCode一致（x64版VSCode必须用x64 Visual Studio Build Tools）
- macOS别用
-stdlib=libstdc++，Linux注意glibc版本——CentOS 7默认只有GLIBC_2.17，但新Node编译产物可能依赖GLIBC_2.28
binding.gyp里target_name和require路径对不上
require('./build/Release/addon')里的addon必须和binding.gyp中"target_name": "addon"完全一致，否则Node根本找不到入口符号。
-
binding.gyp里漏写target_name，node-gyp会生成随机名（如obj.target/addon.node），但require()只认build/Release/<code>target_name.node - 必须加
"cflags": ["-g"]，否则LLDB/GDB无法加载调试符号 - Windows下务必加
"defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]，否则napi.h编译失败 - Linux/macOS若用clang，需补
"xcode_settings": {"CLANG_CXX_LANGUAGE_STANDARD": "c++17"}
launch.json里断点不命中C++代码
VSCode默认的Node调试器（type: "node"）只能停JS，不能进C++；想在C++源码打断点，必须用原生调试器（cppdbg或lldb），且program必须指向node可执行文件本身，不是JS文件。
-
program字段填绝对路径（如/usr/local/bin/node或C:/Program Files/nodejs/node.exe），不能用${workspaceFolder}/index.js -
args才是JS入口：["${workspaceFolder}/index.js"] -
preLaunchTask必须是真正执行npx node-gyp rebuild的任务，且设"group": "build" - 如果用
lldb插件，确保已安装，并在type中明确写"lldb"，不是"node"
Extension Host崩溃报“Extension host terminated”
这不是插件没启起来，而是C++模块在Extension Host进程里触发了段错误或未捕获异常，整个宿主被系统直接杀掉。VSCode日志里看不到堆栈，得脱离VSCode复现。
立即学习“C++免费学习笔记（深入）”；
- 终端里直接运行：
node -e "require('./out/binding.node')"（路径按你项目调整），看是否立刻Segmentation fault - 崩溃时用
lldb（macOS/Linux）或WinDbg（Windows）附加：lldb --node然后run -e "require('./out/binding.node')"，再bt看卡在哪行 - 常见硬伤：Napi::String::New传了
nullptr、Napi::TypedArray::Data()没判null、跨线程调用N-API函数 - 禁用其他插件，最小化工作区（单个
.js+package.json），排除干扰
undefined symbol或段错误。动手前先确认process.version，比盲目重装node-gyp有用得多。 
