Node.js加载C++ Addon（.node文件）失败，如何排查原因？

核心排查步骤（针对Visual Studio项目） #

• 架构必须严丝合缝：Visual Studio项目的目标架构（x86/x64）必须和你运行的Node.js架构完全一致。直接用node -p process.arch查Node.js是32还是64位，然后把项目的解决方案平台改成对应架构，别搞混。
• 揪出缺失的依赖库：.node文件大概率依赖VC++运行时或者其他第三方库，用VS自带的命令提示符运行dumpbin /dependents your_addon.node，看输出里的依赖DLL，确保这些DLL要么和.node文件放一块，要么在系统PATH里能找到。
• NODE_MODULE_VERSION必须匹配：每个Node.js版本对应唯一的模块版本号，用node -p process.versions.modules查当前版本号，然后在项目里：
  • 如果是node-gyp生成的项目，检查binding.gyp里的target配置；
  • 手动建的项目，直接在预处理器定义里加NODE_MODULE_VERSION=xxx（xxx换成查到的数字）。
• 输出设置别搞错：
  • 项目属性→链接器→输出文件，把扩展名改成.node，别生成.dll；
  • 确认输出目录的结构，比如生成的.node要在build/Release/下（bindings包默认找这个路径），或者你require的时候路径要写对。
• 编译选项要对齐：
  • 确保C标准用C17及以上（Node.js v14+都支持）；
  • 预处理器定义里必须加BUILDING_NODE_EXTENSION，这是编译Addon的必要宏；
  • 链接器输入里要正确添加Node.js的lib文件（比如node.lib），路径要对应你安装的Node.js版本目录。
• 清理重建一次：旧缓存坑人，直接删项目的build目录或者VS的输出目录，然后重新生成整个解决方案。

额外验证技巧 #

• 把能正常运行的那个简单项目的VS属性导出（项目→属性→配置属性→常规→导出），然后导入到出问题的项目里，对比差异，重点看架构、预处理器定义、链接器设置、输出路径这些地方。
• 用Process Monitor跟踪Node.js进程，看它加载模块时到底找不到哪个文件，直接定位是.node本身还是依赖的DLL没找到。

内容的提问来源于stack exchange，提问作者manjuv