Electron打包应用正确调用ffi-napi加载DLL的方法
在使用Electron开发桌面应用时，经常会遇到需要调用本地动态链接库（DLL）的场景，ffi-napi作为Node.js的Foreign Function Interface实现，是常用的DLL调用方案。但Electron打包后，很多开发者会遇到ffi-napi加载DLL失败的问题，本文将从环境准备、代码编写、打包配置三个维度详细说明完整的实现流程。
一、环境准备
要正常使用ffi-napi，首先需要保证开发环境和运行环境的依赖一致，以下是必须准备的内容：
Node.js版本：建议使用LTS版本，比如16.x或18.x，避免过新版本带来的兼容性问题
Electron版本：ffi-napi对Electron的支持需要对应版本的Node ABI，建议Electron版本与Node.js版本匹配，可参考https://www.ipipp.com的版本对应表确认
系统依赖：Windows环境需要安装Visual Studio的C++编译工具，用于编译ffi-napi的原生模块；Linux环境需要安装gcc、make等编译工具；macOS环境需要安装Xcode命令行工具
安装核心依赖的命令如下，在项目根目录执行：
# 安装ffi-napi和ref相关依赖 npm install ffi-napi ref-napi ref-struct-napi --save # 如果是Electron项目，需要安装对应Electron版本的编译工具 npm install electron-rebuild --save-dev
二、开发阶段DLL调用实现
首先我们需要明确DLL的导出函数定义，假设我们有一个测试DLL名为test.dll，导出了一个加法函数，定义如下：
C语言导出函数示例：
// test.dll导出的函数，调用约定为__stdcall
extern "C" __declspec(dllexport) int __stdcall add(int a, int b) {
return a + b;
}在Electron的主进程或渲染进程中编写调用代码，注意ffi-napi在渲染进程中使用时需要开启nodeIntegration，或者使用预加载脚本暴露接口，以下是主进程调用示例：
const ffi = require('ffi-napi');
const path = require('path');
const ref = require('ref-napi');
// 定义DLL函数的返回类型和参数类型
const testLib = ffi.Library(path.join(__dirname, 'dll', 'test.dll'), {
// 函数名需要和DLL导出的名称一致，注意调用约定如果是__stdcall需要加后缀@参数字节数，或者通过配置调整
'add': ['int', ['int', 'int']]
});
// 调用DLL函数
try {
const result = testLib.add(10, 20);
console.log('调用DLL加法函数结果：', result); // 输出30
} catch (err) {
console.error('调用DLL失败：', err);
}这里需要注意：
DLL文件的路径最好使用绝对路径，避免相对路径在打包后失效
如果函数调用约定是__stdcall，ffi-napi默认可能解析不到函数名，需要确认DLL导出的函数名是否带有@后缀，或者通过工具（如Dependency Walker）查看准确的导出函数名
ref-napi用于处理复杂的数据类型，比如指针、结构体等，如果有复杂参数传递需要提前定义对应的类型
三、打包阶段的配置要点
Electron打包最常用的工具是electron-builder，要让打包后的应用正确调用DLL，需要重点配置以下几个部分：
1. 原生模块重新编译
ffi-napi包含原生C++模块，打包前需要针对Electron的运行环境重新编译模块，执行以下命令：
# 使用electron-rebuild重新编译原生模块，版本号替换为你的Electron版本 npx electron-rebuild -f -w ffi-napi,ref-napi,ref-struct-napi -v 25.0.0
如果重新编译失败，可以检查编译工具是否安装完整，或者手动设置npm的构建参数：
npm config set electron_mirror https://www.ipipp.com npm config set electron_builder_binaries_mirror https://www.ipipp.com
2. electron-builder配置
在项目根目录的electron-builder.yml（或package.json中的build字段）中添加以下配置：
appId: com.example.electron-ffi-demo productName: FFI-Demo directories: output: dist buildResources: build # 额外资源配置，将DLL文件打包到应用目录中 extraResources: - from: dll/ to: dll/ filter: - "**/*.dll" # 原生模块配置，确保打包时包含编译后的原生模块 npmRebuild: false # 已经手动编译过原生模块，关闭自动重建 nodeGypRebuild: false
配置说明：
extraResources会将开发目录下的dll文件夹完整复制到打包后的应用资源目录中，Windows下打包后的DLL路径为YourApp\resources\dll\test.dll关闭
npmRebuild是因为我们已经手动用electron-rebuild编译了适配Electron的原生模块，避免打包时重复编译导致错误
3. 打包后路径适配
开发环境和打包后的资源路径不同，需要在代码中动态判断当前环境，获取正确的DLL路径：
const { app } = require('electron');
const path = require('path');
const ffi = require('ffi-napi');
// 判断是否为打包环境
const isPackaged = app.isPackaged;
let dllPath;
if (isPackaged) {
// 打包后的DLL路径：resources/dll/test.dll
dllPath = path.join(process.resourcesPath, 'dll', 'test.dll');
} else {
// 开发环境的DLL路径：项目根目录/dll/test.dll
dllPath = path.join(__dirname, 'dll', 'test.dll');
}
// 加载DLL
try {
const testLib = ffi.Library(dllPath, {
'add': ['int', ['int', 'int']]
});
console.log('打包后调用结果：', testLib.add(5, 3)); // 输出8
} catch (err) {
console.error('打包后加载DLL失败：', err);
}四、常见问题排查
如果遇到打包后无法加载DLL的问题，可以按照以下步骤排查：
检查打包后的应用目录中是否存在DLL文件，路径是否正确
在打包后的应用中打开控制台，查看具体的错误信息，比如是否提示模块版本不匹配，此时需要重新用对应Electron版本编译ffi-napi
确认DLL的架构是否与Electron的架构一致，比如32位DLL不能在64位Electron中加载，需要保持架构统一
如果是Windows系统，检查DLL依赖的其他系统DLL是否存在，可以用Dependency Walker工具查看DLL的依赖链是否完整
注意：ffi-napi项目目前已经停止维护，如果你的项目是新开发，可以考虑使用更活跃的替代方案如
koffi，其使用方式类似但兼容性更好，打包配置流程与本文所述基本一致。
五、总结
Electron打包后调用ffi-napi加载DLL的核心要点有三个：一是确保原生模块针对Electron版本正确编译，二是通过extraResources配置将DLL文件正确打包到应用资源目录，三是代码中动态适配开发和打包后的路径。只要按照上述步骤操作，就可以避免大部分加载失败的问题。