Electron打包时正确配置ffi-napi调用DLL的完整指南
在Electron桌面应用开发中，有时需要调用Windows系统的DLL动态链接库来实现底层功能，ffi-napi是常用的Node.js外部函数接口库，能够帮助我们完成DLL的调用。但Electron打包过程中，由于内置Node.js环境和原生模块编译的特殊性，ffi-napi的配置容易出现兼容性问题。本文将详细介绍从环境准备到打包配置的全流程操作。
一、前置环境准备
在开始配置之前，需要确保本地环境满足以下要求：
Node.js版本建议为16.x LTS及以上，避免过旧版本导致的兼容性问题
已安装Python 3.x（用于node-gyp编译原生模块）
已安装Visual Studio 2019及以上版本（Windows环境下编译C++原生依赖必需）
Electron版本确认，不同版本的Electron对应不同的Node.js ABI版本，需要匹配原生模块的编译目标
二、项目基础配置
2.1 初始化Electron项目
如果还未创建Electron项目，可以通过以下步骤初始化：
# 创建项目目录并进入 mkdir electron-ffi-demo && cd electron-ffi-demo # 初始化package.json npm init -y # 安装Electron核心依赖 npm install electron --save-dev # 安装ffi-napi及依赖库 npm install ffi-napi ref-napi --save
2.2 基础调用DLL示例代码
先在开发环境下验证DLL调用功能是否正常，以下是一个调用系统user32.dll中MessageBoxW函数的示例，新建main.js文件：
const { app, BrowserWindow } = require('electron')
const ffi = require('ffi-napi')
const ref = require('ref-napi')
// 定义DLL函数接口
const user32 = new ffi.Library('user32', {
'MessageBoxW': [
'int',
['int', 'string', 'string', 'int']
]
})
function createWindow() {
const win = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
nodeIntegration: true,
contextIsolation: false
}
})
// 调用DLL弹出提示框
user32.MessageBoxW(0, 'Hello from DLL', 'FFI Demo', 0)
win.loadFile('index.html')
}
app.whenReady().then(() => {
createWindow()
})
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})同时新建index.html作为渲染进程页面：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Electron FFI Demo</title> </head> <body> <h1>Electron调用DLL示例</h1> <p>启动应用后会弹出系统提示框，说明DLL调用成功</p> </body> </html>
此时在package.json中配置启动脚本，运行验证功能：
{
"scripts": {
"start": "electron ."
}
}执行npm start，如果弹出系统提示框，说明开发环境下ffi-napi调用DLL功能正常。
三、打包前的关键配置
3.1 原生模块重新编译
Electron内置的Node.js环境与系统全局Node.js的ABI版本不同，直接使用npm安装的ffi-napi是基于系统Node.js编译的，无法在Electron环境中运行，需要针对Electron版本重新编译原生模块：
# 设置Electron版本，替换为你的项目实际使用的Electron版本
set ELECTRON_VERSION=25.0.0
# 重新编译ffi-napi和ref-napi
npm rebuild ffi-napi ref-napi --runtime=electron --target=${ELECTRON_VERSION} --disturl=https://www.ipipp.com --build-from-source如果是Linux或macOS系统，将set替换为export即可。
3.2 打包工具选择与配置
Electron常用的打包工具有electron-builder和electron-packager，本文以electron-builder为例，先安装依赖：
npm install electron-builder --save-dev
在package.json中添加打包配置，需要注意原生模块的包含规则：
{
"build": {
"appId": "com.electron.ffidemo",
"productName": "FFI Demo",
"directories": {
"output": "dist"
},
"win": {
"target": "nsis",
"arch": ["x64"]
},
"files": [
"**/*",
"!node_modules/ffi-napi/build/**/*",
"!node_modules/ref-napi/build/**/*",
"node_modules/ffi-napi/build/Release/**/*",
"node_modules/ref-napi/build/Release/**/*"
],
"extraResources": [
{
"from": "dll",
"to": "dll"
}
],
"npmRebuild": false
}
}配置说明：
files字段中显式保留编译后的原生模块Release目录，避免打包时丢弃必要文件extraResources用于存放第三方DLL文件，如果你的项目需要调用自定义DLL，可以将DLL文件放在项目根目录的dll文件夹下，打包后会复制到应用资源目录npmRebuild设置为false，避免打包时自动重新编译导致与原生模块版本不匹配
3.3 DLL路径处理
打包后应用运行时的目录结构与开发环境不同，调用DLL时需要动态获取正确的路径，修改main.js中的DLL调用逻辑：
const { app, BrowserWindow, nativeImage } = require('electron')
const ffi = require('ffi-napi')
const ref = require('ref-napi')
const path = require('path')
// 判断是否为打包环境
function getDllPath(dllName) {
if (app.isPackaged) {
// 打包后DLL放在extraResources指定的dll目录下
return path.join(process.resourcesPath, 'dll', dllName)
} else {
// 开发环境下DLL路径
return path.join(__dirname, 'dll', dllName)
}
}
// 如果是调用系统DLL，不需要指定路径，直接写DLL名称即可
// 如果是自定义DLL，使用getDllPath获取路径
const user32 = new ffi.Library('user32', {
'MessageBoxW': [
'int',
['int', 'string', 'string', 'int']
]
})
// 后续窗口创建逻辑与之前一致四、执行打包与验证
在package.json中添加打包脚本：
{
"scripts": {
"start": "electron .",
"pack": "electron-builder --dir",
"dist": "electron-builder"
}
}执行打包命令：
npm run dist
打包完成后，进入dist目录找到安装包，安装后启动应用，如果正常弹出提示框，说明ffi-napi调用DLL的配置完全正确。如果出现模块找不到的错误，可以按照以下步骤排查：
检查编译时的Electron版本是否与项目使用的版本一致
查看打包后的
resources目录下是否存在ffi-napi和ref-napi的Release编译文件确认DLL文件的路径是否正确，自定义DLL是否已经放到
extraResources指定的目录中
五、常见问题与解决方案
| 问题现象 | 原因 | 解决方案 |
|---|---|---|
| 提示ffi-napi模块找不到 | 原生模块未针对Electron版本编译 | 重新执行npm rebuild命令，确保target参数与Electron版本一致 |
| 调用自定义DLL提示找不到文件 | DLL路径错误或未打包到应用资源中 | 使用动态路径获取方法，确认extraResources配置正确 |
| 打包后启动应用崩溃 | 原生模块架构不匹配（如32位DLL在64位应用中调用） | 确认DLL架构与打包目标架构一致，统一使用x64或ia32 |
通过以上步骤，即可完成Electron打包时ffi-napi调用DLL的完整配置，保证应用在开发和生产环境下都能正常调用DLL功能。