electron-builder打包报错Plugin not found: NSIS UAC插件缺失排查与修复

electron-builder打包报错Plugin not found: NSIS UAC插件缺失排查与修复

发布时间：2026/10/18 4:01:19
electron-builder打包报错Plugin not found: NSIS UAC插件缺失排查与修复 如果你的 Windows 打包流水线某天突然在 electron-builder 这个环节报出Plugin not found, cannot call UAC::_别急着怀疑安装包损坏或者想着重装 Node 环境。这个报错既不是 exe 资源问题也不是 Electron 主进程的代码问题它发生在打包工具的 NSIS 脚本编译阶段处理起来其实有固定套路。我第一次遇到时也很懵项目本身跑得好好的electron-builder 之前也打包过好几个版本突然某个版本开始出现这个错误。当时第一反应是翻 electron-builder 的 issue搜到的答案五花八门有人说是 NSIS 版本问题有人说是缓存问题还有人让重装系统结果都不对症。后来把一个包含 UAC 逻辑的自定义 NSIS 脚本从上到下拆开看才明白问题出在哪儿。这篇文章把我当时的完整排查链路和最终落地的修复方案写出来。如果你也在自定义 NSIS 脚本里写过 UAC 相关的代码或者准备把一套老 NSIS 脚本迁移到 electron-builder 下这篇能帮你少走不少弯路。1. 报错的全貌它发生在编译期不是安装期1.1 一次典型的报错现场先看一个典型场景。某一次打包终端输出大概长这样• building block map ... • packaging ... • building installer ... Plugin not found, cannot call UAC::_前面一切都正常走到building installer阶段后makensis 直接终止后面不会再有任何安装包产出。整个过程并不是安装包运行的时候报错而是生成安装包的那一步就挂了。这个细节很重要很多人会误以为是安装程序在用户机器上出了问题实际上问题出在编译 NSIS 脚本的阶段连产物都没生成。配合这个报错的往往还有一个自定义 NSIS 脚本比如项目里配置了这样的内容nsis: script: build/installer.nsi而installer.nsi里大概包含类似代码!include UAC.nsh Function .onInit !insertmacro UAC_INIT FunctionEnd或者更直接一点UAC::RunElevated报错信息里那句Plugin not found, cannot call UAC::_其中的UAC就是 NSIS 的一个第三方插件UAC::_指的是这个插件导出的函数命名空间。makensis 编译脚本时只要遇到UAC::开头的调用就会去插件的搜索路径里找UAC.dll找不到就立刻报这个错。1.2 NSIS 插件机制和 electron-builder 默认环境的差异要理解为什么 electron-builder 环境下特别容易出这个问题得先搞清楚 makensis 的插件工作方式。NSIS 的插件分为两类一类是 DLL 形式的插件比如 UAC.dll函数调用语法就是插件名::函数名另一类是宏文件比如 UAC.nsh通过!include引入。DLL 文件通常放在 NSIS 安装目录的Plugins文件夹里宏文件放在Include文件夹里。当你使用官方 NSIS 工具链时Plugins和Include目录是现成的装插件就是解压复制。但在 electron-builder 的场景下它并不使用你系统里那个完整 NSIS 安装目录而是从缓存里解压一套自己内置的 NSIS这套环境里只有官方自带的那些插件。你自定义脚本里!include UAC.nsh和UAC::_所需要的第三方文件在 electron-builder 的默认 NSIS 缓存目录里根本不存在。于是 makensis 在解析阶段就停住了抛出的就是那个Plugin not found。说白了这个问题不是 electron-builder 的 bug而是它提供了一个干净的编译环境你的脚本却默认了所有第三方插件都存在。两种环境的搜索路径和资源目录不一样脚本一旦搬过去冲突就爆发了。2. 完整排查链路从复制日志到最小化复现2.1 先把 electron-builder 的隐藏编译过程挖出来遇到这个报错很多人第一件事就是去搜索引擎复制报错文本。但与其搜答案不如先看自己机器的实际情况。electron-builder 打包时会把 NSIS 解压到缓存目录Windows 下通常是%LOCALAPPDATA%\electron-builder\Cache\nsis这个目录下有按版本号命名的子目录比如nsis-3.0.4.1。打开子目录你能看到一套完整的 NSIS 程序里面有makensis.exe、Include目录、Plugins目录、Stubs目录等等。然后去看Plugins目录里有哪些文件。拿这套环境去检查你的自定义脚本基本就能对上号如果脚本里写了UAC::_而Plugins目录下根本没有UAC.dll报错就是必然的。还可以做一步更细致的操作在打包命令里加上--verbose或者直接查看 electron-builder 的调试日志日志里会打印出它实际执行的 makensis 命令。你会在命令里看到它把 NSIS 根目录指向了缓存目录makensis.exe -D... -I... 打包临时目录\app.nsi看到这个命令你就能确认它不是用你系统里安装的 NSIS而是用缓存里那套原装环境。2.2 用最小项目确认报错触发条件光看日志还不够我习惯用一个最小项目把问题固定下来避免被项目本身的其他因素干扰。新建一个最简单的 Electron 项目只放一个package.json和一个main.js然后加一个installer.nsi内容精简到只有触发问题的最少代码!include UAC.nsh Section UAC::RunElevated SectionEnd在package.json里配置{ build: { nsis: { script: installer.nsi } } }然后跑打包命令是不是 100% 复现如果复现了就说明问题和你主项目本身的业务代码没有关系唯一的关系就是那个自定义脚本。这时候再做一个反向实验把脚本里所有UAC::和!include UAC.nsh注释掉重新打包。如果打包通过了那根因就彻底锁定了脚本引用了当前编译环境里不存在的插件导致 makensis 编译中止。这个最小化复现的方法看起来有点笨但好处很明显一是能快速判断是不是脚本里的第三方依赖问题二是后续验证修复方案时有一个干净稳定的对照组。2.3 根因定性是 DLL 路径问题不是脚本逻辑问题很多人的疑问是为什么 NSIS 没把错误定成语法错误或者函数未定义偏偏是Plugin not found因为 NSIS 的插件调用分两步第一步是解析UAC::这个命名空间去插件搜索路径里找对应的 DLL第二步才是真正解析 DLL 导出的函数签名。Plugin not found是第一步就失败了还没有机会走到函数解析所以根本不是脚本逻辑写错了。这也就意味着你花时间检查UAC_INIT宏的参数、调换函数调用顺序、修改权限逻辑都没有意义。方向应该是让 makensis 能够找到UAC.dll或者让脚本彻底不再依赖这个 DLL。把排查方向从脚本逻辑切换到插件资源路径这个问题就已经解决了一半。3. 三种修复思路和我在实际项目中最终选择的方案3.1 方案一让自定义脚本彻底告别 UAC 插件先问一个问题你的安装脚本里为什么需要 UAC 插件我见过的案例里90% 都是因为想要下面几个能力之一安装到 Program Files 等需要管理员权限的目录安装程序请求提权以管理员身份执行安装逻辑安装完成后以管理员权限运行主程序。这些需求其实 electron-builder 自带的 NSIS 配置已经覆盖了大部分不需要你自己写 UAC 插件代码。比如安装到管理员目录可以直接配置nsis: perMachine: trueperMachine: true会让安装器以机器级方式安装默认会请求提升权限正好对应你想要的 UAC 弹窗。配合nsis: allowElevation: true可以让安装完成后的运行阶段拿到提升权限。如果你的需求只是安装到 Program Files 并且安装时弹 UAC那直接删掉脚本里的所有 UAC 内容改用perMachine就够了。实测下来这套方案在多数普通项目中完全够用安装程序会弹 UAC安装目录默认跳到 Program Files卸载也能正常清理注册表。代码层面要做的就是把自定义installer.nsi里的 UAC 部分删掉甚至干脆删掉整个自定义脚本使用 electron-builder 的默认脚本。当时我的项目里有一个三十多行的 UAC 控制块最后被压成了下面这几行配置nsis: oneClick: false perMachine: true allowElevation: true allowToChangeInstallationDirectory: true打包一次通过安装流程行为没有变化UAC 弹窗照样出来问题直接消失。这是最干净、最可持续的方案。3.2 方案二用!addplugindir把自定义插件目录指给编译器如果你的自定义脚本确实深度依赖 UAC 插件的某些能力临时改写成 electron-builder 配置不现实那就需要让 makensis 能找到插件。NSIS 提供了一个编译指令!addplugindir可以在脚本中追加插件搜索目录。比如在installer.nsi开头加上!addplugindir ${BUILD_RESOURCES_DIR}\nsis-plugins !include UAC.nsh然后在项目的 buildResources 目录默认是build下建一个nsis-plugins文件夹把UAC.dll放进去。${BUILD_RESOURCES_DIR}是 electron-builder 注入的宏指向你的 buildResources 目录。这样脚本就不依赖系统环境不管在哪台机器上构建都能通过项目内的目录找到插件。需要注意一个细节UAC.dll和UAC.nsh是两个不同文件!addplugindir只解决 DLL 的位置问题UAC.nsh宏文件的路径要靠!include自己控制。建议把UAC.nsh也放到 buildResources 下然后在脚本里用相对路径或者另一个宏来定位。我这里用了一个比较稳妥的写法在installer.nsi里!addplugindir ${BUILD_RESOURCES_DIR}\nsis-plugins !include ${BUILD_RESOURCES_DIR}\UAC.nsh把UAC.dll放在build\nsis-plugins\下把UAC.nsh放在build\下。这样一个项目目录自包含团队里其他人拉代码后也能直接打包不用每个人手动去改缓存目录。这个方案有验证成本我建议先在最小复现项目里验证通过再合并回主项目。因为不同 electron-builder 版本注入的宏和环境变量略有差异但BUILD_RESOURCES_DIR这个宏在较新的版本里是稳定的。3.3 方案三直接在缓存 NSIS 环境里塞插件不推荐但可应急还有一个立竿见影的应急办法找到 electron-builder 的 NSIS 缓存目录把UAC.dll复制到它的Plugins文件夹下。比如%LOCALAPPDATA%\electron-builder\Cache\nsis\nsis-3.0.4.1\Plugins\然后再打包。只要缓存还在makensis 编译时就能找到插件报错消失。很多网上流传的复制 DLL 到 NSIS 目录的解法本质上就是这个。但我不推荐把它作为正式方案原因有两个第一electron-builder 在版本升级或者缓存被清理后会重新解压一套干净的 NSIS你手动放进去的文件会丢失问题会再次出现。也就是说它是一次性的、不可复现的修复。第二团队成员各自构建时如果每个人都要手动操作缓存目录环境就不可控了。某个新同事拉完代码直接打包大概率又会撞上同样的报错然后一脸茫然。这个方案我只会用在今天必须出一个安装包、插件目录临时找不到的极端场景下作为短期止血手段。修复完成之后仍然需要回归方案一或者方案二。3.4 我的取舍思路三个方案里我最终选择的是方案一。原因很实际那个自定义脚本里大段 UAC 代码最终目的只是希望安装到 Program Files 后能正常请求管理员权限。而这个需求electron-builder 的perMachine配置已经实现了。如果你问我什么时候用方案二我的判断标准是脚本里是否真的用到了 UAC 的交互式状态判断比如判断当前进程是否已经是管理员、是否需要切换用户令牌、在安装过程中做精细化的权限分支处理。只有这种高度定制化的场景才值得保留 UAC 插件调用。普通场景下electron-builder 内置的提权流程比你自己用 UAC 插件拼出来的半吊子流程稳定得多。还有一点自定义 NSIS 脚本越薄越好。electron-builder 的设计哲学是用配置文件代替脚本它能通过 YAML 配置表达的安装行为就不要写 NSIS 代码。脚本一旦变厚兼容性风险和排查成本都会上升这次踩的坑就是一个很好的警告。4. 修复后需要一起检查的关联项4.1 安装行为验证清单删掉 UAC 插件代码、改成配置之后不能只看打包不报错就以为完事了安装行为还得分项验证一遍。我在实际项目中列过一个清单你可以直接抄双击安装包确认 UAC 盾牌提示是否正常出现确认安装目录是否默认指向 Program Files对应perMachine配置安装过程中是否能正常切换安装目录对应allowToChangeInstallationDirectory安装完成后启动程序检查进程权限是否符合预期任务管理器里看进程是否带管理员标志从控制面板卸载确认卸载过程也能触发 UAC 提权用常规用户账号跑一遍安装和卸载确认没有权限报错。这几个项目里最容易忽略的是第 6 项。很多开发者的测试账号本身就是管理员普通用户场景下权限问题根本测不出来。建议临时创建一个标准的非管理员账号专门做这个验证。4.2 执行权限、签名和缓存这几个连带坑修复 UAC 插件问题之后有另外几个和权限相关的坑会跟着暴露出来提前说一下省得你反复试。第一个是未签名安装包的 SmartScreen 拦截。如果你用的是自签名证书或者没配证书安装包在 Windows 上会有蓝色弹窗提示。这个跟 UAC 插件无关但经常被人混淆以为是提权配置有问题。第二个是缓存版本对齐问题。项目里如果锁定了 electron-builder 版本但团队同事的%LOCALAPPDATA%\electron-builder\Cache里有旧版本下载残留有可能出现我这边打包正常同事那边报错的情况。统一的做法是让 CI 或构建脚本每次先清理 electron-builder 的 NSIS 缓存让它重新下载解压保证环境干净。这个习惯还能顺带排查好多隐蔽的 NSIS 问题。第三个和requestedExecutionLevel有关。electron-builder 的win配置里有这个选项它直接控制打包出来的 exe 的 manifest 信息。如果这里设置了requireAdministrator那应用启动本身就会请求管理员权限跟安装时 UAC 逻辑是两码事。不要把nsis和win两个配置层面的权限设置搞混。4.3 自定义 NSIS 迁移时常见的其他报错对照UAC 插件不是唯一一个会在 electron-builder 下翻车的第三方 NSIS 组件。我整理过一份从老 NSIS 项目迁移到 electron-builder 时常遇到的报错对照表报错或现象真正原因处理方式Plugin not found, cannot call XXX::_引用的插件 DLL 不在 electron-builder 内置 NSIS 环境中要么用!addplugindir指向项目内插件目录要么改写配置去掉插件!include: could not find file: MUI2.nsh需要的官方宏文件没有被正确加入搜索路径用nsis.include指向对应 nsh 文件或者把宏文件放入 buildResourcesUnresolved symbol: XXX脚本里用了 NSIS 内置函数但写错名称或引用了不存在函数检查函数名拼写对照 NSIS 文档确认调用语法安装包能生成但运行时脚本段崩溃脚本中使用了不该出现在运行期的宏把非编译期逻辑移到正确事件回调中安装完成后程序没有以管理员权限运行依赖Exec启动但未做提权处理改用ExecShell或调整应用层提权方案这些对照关系的价值在于遇到类似问题可以先定位到编译期还是运行期再决定查插件路径还是查脚本逻辑不浪费时间。5. 一点实操体会回过头看这个报错它本身并不难解决难的是很多人一开始根本不知道 electron-builder 用的是缓存里那套独立 NSIS更不知道第三方插件需要在编译前进入插件的搜索路径。我个人现在的习惯是所有 NSIS 自定义脚本都遵守三条规则第一不轻易引入第三方插件能靠 electron-builder 配置实现的需求就不碰脚本第二如果实在要用插件就把插件文件放在项目 buildResources 目录内让项目自包含绝不让团队成员手动操作缓存目录第三脚本里每一个第三方依赖都写明版本和使用理由避免半年后自己都忘了这段代码干嘛的。如果你也踩到了这个报错建议就按文章里的顺序来先确认是不是编译期报错再看脚本里有没有 UAC 相关调用然后用最小项目复现最后根据实际需求选择删插件还是补插件目录。多数项目的答案都是前者你可以少折腾一些。