VSCode调试Node.js原生Addon需确保binding.gyp中target_name、cflags（含-g）、ABI与Node版本严格对齐，launch.json中program设为"node"、args指向JS入口、preLaunchTask执行npx node-gyp rebuild，且修改gyp后必须手动clean并rebuild。
VSCode 能跑通 Node.js 原生Addon的混合调试，但默认配置下几乎必然失败——不是 node-gyp 编译报错，就是断点不命中、符号缺失或 Cannot find module './build/Release/addon'。核心问题不在“能不能”，而在“路径、ABI、构建产物三者是否严格对齐”。
binding.gyp 必须显式指定 target_name 和 cflags
很多人直接复制官网示例，binding.gyp 里只写 "sources": ["addon.cpp"]，结果编译出的 .node 文件名是随机的（如 build/Release/obj.target/addon.node），而 Node.js 加载时默认找的是 build/Release/<code>target_name.node。两者不一致，require() 直接抛错。
-
target_name必须与require('./build/Release/xxx')中的xxx完全一致（不含.node后缀） -
cflags或cflags_cc需加-g，否则 GDB/LLDB 无法加载调试符号 - Windows 下必须加
"defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]，否则napi.h编译失败 - Linux/macOS 若用 clang，需额外加
"xcode_settings": {"CLANG_CXX_LANGUAGE_STANDARD": "c++17"}或对应gcc的-std=c++17
正确示例：
{
"targets": [{
"target_name": "addon",
"sources": ["addon.cpp"],
"cflags!": ["-fno-exceptions"],
"cflags_cc!": ["-fno-exceptions"],
"cflags": ["-g"],
"conditions": [
["OS=='win'", {
"defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]
}]
]
}]
}
launch.json 中 preLaunchTask 必须触发 node-gyp rebuild
VSCode 默认的 g++ 构建任务对Addon无效——它不会生成 .node，也不会处理 node_modules 依赖和 ABI 版本校验。断点打在 C++ 里，但程序根本没加载你的原生模块，自然停不住。
立即学习“C++免费学习笔记（深入）”；
-
preLaunchTask必须指向一个真正执行node-gyp rebuild的 task，不能是通用编译任务 - task 的
command应为npx node-gyp rebuild（推荐）或全局node-gyp rebuild - 必须设置
"group": "build"，否则 VSCode 不识别为构建任务 - 若用 Python 3.x，需确保
node-gyp已适配（npm install -g node-gyp@9+），否则报Python 2.7 required
对应 tasks.json 片段：
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
{
"version": "2.0.0",
"tasks": [{
"label": "npm: rebuild addon",
"type": "shell",
"command": "npx node-gyp rebuild",
"group": "build",
"presentation": { "echo": true, "reveal": "silent", "panel": "shared" }
}]
}
调试时 program 必须是 node，args 必须指向 JS 入口文件
有人把 program 设成 ${workspaceFolder}/build/Release/addon.node，这是错的——.node 是动态库，不是可执行文件。VSCode 会直接报 spawn XXX failed。
-
program只能是node（系统 PATH 中的可执行文件） -
args必须是 JS 入口，比如["${workspaceFolder}/index.js"]，且该文件中必须有require('./build/Release/addon') -
cwd必须设为${workspaceFolder}，否则require相对路径失效 -
externalConsole建议设为true（尤其 Windows），否则 stdout/stderr 可能被截断，看不到console.log或 native 错误
launch.json 关键字段：
{
"type": "node",
"request": "launch",
"name": "Debug Addon",
"program": "node",
"args": ["${workspaceFolder}/index.js"],
"cwd": "${workspaceFolder}",
"env": { "NODE_ENV": "development" }
}
常见符号缺失：.node 文件没 debug info 或 ABI 不匹配
断点灰色、提示 Breakpoint ignored because generated code not found，大概率是 .node 没带调试符号，或 Node.js 运行时 ABI 与编译时 ABI 不一致（比如用 Node 18 编译，却用 Node 20 运行）。
- 检查
build/Release/addon.node是否含调试信息：file build/Release/addon.node（Linux/macOS）或dumpbin /headers build\Release\addon.node（Windows），应含debug字样 - 确认
node -p process.versions.modules输出值（如115）与node-gyp编译时使用的--target一致；不一致就加--target=18.19.0显式指定 - Windows 上若用 MSVC 编译，必须用
node-gyp rebuild --msvs_version=2022，否则链接器找不到node.lib - Linux 上若用 GCC，确保
gdb版本 ≥ 8.0，旧版无法解析 DWARF5 符号
ABI 不匹配时，require() 会直接抛 Error: Module version mismatch，而不是静默失败——这个错误比断点不命中更容易定位。
最易被忽略的点：binding.gyp 修改后必须手动运行 npx node-gyp clean && npx node-gyp rebuild，VSCode 不会自动感知 gyp 文件变更并重编；哪怕只改了一个空格，旧的 .node 文件仍会被加载，导致所有调试行为失真。
