使用node-addon-api链接子目录C共享库时报image not found错误

问题根因 #

该报错是动态链接器运行时无法定位预编译共享库导致的，和编译阶段的include_dirs配置无关：include_dirs仅作用于头文件搜索阶段，运行时动态库加载完全依赖系统动态链接器的路径搜索规则。你修改路径后没有正确配置.node模块的运行时搜索路径（rpath），同时Go编译的共享库默认的安装名（install name，macOS特有）不符合加载要求。

修复步骤 #

1. 统一目录结构与文件命名 #

先确认各平台的共享库后缀符合规范：

• macOS 使用 .dylib 后缀
• Linux 使用 .so 后缀
• Windows 使用 .dll 后缀

目录结构参考：

项目根目录
├── binding.gyp
├── macos-arm64
│   ├── libmylib.dylib
│   └── mylib.h
├── linux-x64
│   ├── libmylib.so
│   └── mylib.h
└── src
    └── addon.cpp

2. 修改binding.gyp配置 #

直接使用node-gyp内置的OS、target_arch变量自动匹配对应架构目录，同时分平台配置rpath和后处理逻辑：

{
  "targets": [
    {
      "target_name": "mylib",
      "sources": ["src/addon.cpp"],
      "include_dirs": [
        "<!(node -p \"require('node-addon-api').include\")",
        "<(OS)-<(target_arch)"
      ],
      "conditions": [
        ["OS=='mac'", {
          "libraries": [
            "-L<(OS)-<(target_arch)",
            "-lmylib",
            "-Wl,-rpath,@loader_path/../../<(OS)-<(target_arch)"
          ],
          "postbuilds": [
            {
              "postbuild_name": "Fix dylib install name",
              "action": ["install_name_tool", "-change", "libmylib.dylib", "@rpath/libmylib.dylib", "<(PRODUCT_DIR)/mylib.node"]
            }
          ]
        }],
        ["OS=='linux'", {
          "libraries": [
            "-L<(OS)-<(target_arch)",
            "-lmylib",
            "-Wl,-rpath,$ORIGIN/../../<(OS)-<(target_arch)"
          ]
        }]
      ]
    }
  ]
}

配置说明：

• macOS下的@loader_path代指编译生成的mylib.node文件所在目录（默认是build/Release），../../退回到项目根目录后即可定位到架构子目录
• 新增的macOS后处理步骤是为了修正Go编译的dylib默认不带@rpath前缀的安装名，让动态链接器从配置的rpath路径搜索库文件
• Linux下的$ORIGIN作用和macOS的@loader_path完全一致，指向.node模块所在目录

3. 验证配置生效 #

编译完成后执行对应命令验证：

• macOS：执行otool -L build/Release/mylib.node，正常输出中libmylib.dylib的路径应为@rpath/libmylib.dylib；执行otool -l build/Release/mylib.node | grep LC_RPATH -A2可以确认rpath路径是否指向你的架构子目录
• Linux：执行ldd build/Release/mylib.node，输出中libmylib.so的路径应显示为你的架构子目录下的绝对路径

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