Electron-Builder项目NSIS配置完全指南

柯晶辰Godfrey

于 2025-06-03 09:00:11 发布

阅读量345

点赞数 5

本文链接：https://blog.youkuaiyun.com/gitblog_00403/article/details/148391554

版权

Electron-Builder项目NSIS配置完全指南

electron-builder A complete solution to package and build a ready for distribution Electron app with “auto update” support out of the box 项目地址: https://gitcode.com/gh_mirrors/el/electron-builder

前言

在开发Electron应用时，打包和分发是重要环节。electron-builder作为流行的打包工具，提供了强大的Windows平台支持，其中NSIS（Nullsoft Scriptable Install System）是其默认的Windows安装程序解决方案。本文将深入解析electron-builder中NSIS配置的各个方面，帮助开发者构建专业的Windows安装程序。

NSIS基础配置

electron-builder的顶层配置中，nsis键包含了构建NSIS目标的所有选项。这些配置同样适用于Web安装程序，只需使用顶层nsisWeb键即可。

默认情况下，electron-builder启用了NSIS的Unicode支持，并扩展了字符串长度限制（从默认的1024字节提升到8192字节），这为多语言支持和复杂安装逻辑提供了更好的基础。

多架构支持

electron-builder的一个强大特性是能够同时构建32位(ia32)和64位(x64)架构的安装包：

当同时构建两种架构时（使用--x64 --ia32参数），最终只会生成一个安装程序
安装程序会自动检测系统架构并安装对应的版本
这一特性同样适用于Web安装程序（nsis-web目标）

这种智能的架构处理大大简化了分发流程，用户无需关心自己系统的架构类型。

Web安装程序详解

Web安装程序是一种更高效的安装方案：

构建方式：设置构建目标为nsis-web
工作原理：
- 安装程序体积小，只包含核心安装逻辑
- 运行时自动检测系统架构
- 从网络下载对应的完整安装包
优势：
- 用户无需手动选择架构版本
- 避免将多个架构的包捆绑在一起
- 特别适合大型应用程序的分发

自定义Web安装程序需要使用nsisWeb键而非普通的nsis键。

离线安装方案：

将下载的包文件放在安装程序同一目录下，安装程序会自动检测并使用
使用--package-file=path_to_file参数指定本地包文件

自定义NSIS脚本进阶

electron-builder提供了两种自定义NSIS脚本的方式：

include：推荐方式，在默认脚本基础上进行定制
script：完全自定义脚本，适用于特殊需求

自定义宏实现

通过创建build/installer.nsh文件，可以定义多种自定义宏：

!macro customHeader
  !system "echo '' > ${BUILD_RESOURCES_DIR}/customHeader"
!macroend

!macro preInit
  ; 在NSIS .OnInit回调开头插入
  !system "echo '' > ${BUILD_RESOURCES_DIR}/preInit"
!macroend

可用宏包括：

customHeader：自定义安装程序头部
preInit/customInit：初始化阶段定制
customInstall/customUnInstall：安装/卸载过程定制
customInstallMode：安装模式控制
customWelcomePage：自定义欢迎页面

环境变量说明

BUILD_RESOURCES_DIR：构建资源目录
PROJECT_DIR：项目目录
build目录自动加入包含路径
插件目录自动包含x86-unicode和x86-ansi版本

添加额外资源

可以在build目录中添加额外资源并在安装过程中使用：

!macro customInstall
  File /oname=$PLUGINSDIR\extramsi.msi "${BUILD_RESOURCES_DIR}\extramsi.msi"
  ExecWait '"msiexec" /i "$PLUGINSDIR\extramsi.msi" /passive'
!macroend

区分安装与更新

使用${isUpdated}变量可以区分全新安装和更新操作：

${ifNot} ${isUpdated}
  ; 仅在新安装时执行的代码
${endIf}

GUID与应用程序标识

Windows安装程序需要使用注册表键，electron-builder提供了灵活的标识方案：

自动生成：基于appId或name生成UUID v5
显式设置：通过nsis.guid选项（不推荐）
重要原则：应用发布后不应更改appId

AUMID设置：对于Windows 8+/10的通知功能，应在主进程中尽早设置：

app.setAppUserModelId(appId)

便携版应用

构建便携版应用需设置目标为portable，或使用--win portable参数。

便携版提供以下环境变量：

PORTABLE_EXECUTABLE_FILE：可执行文件路径
PORTABLE_EXECUTABLE_DIR：可执行文件所在目录
PORTABLE_EXECUTABLE_APP_FILENAME：净化后的应用名（用于文件路径）

常见问题解决方案

修改默认安装目录

!macro preInit
  SetRegView 64
  WriteRegExpandStr HKLM "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
  WriteRegExpandStr HKCU "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
  SetRegView 32
  WriteRegExpandStr HKLM "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
  WriteRegExpandStr HKCU "${INSTALL_REGISTRY_KEY}" InstallLocation "C:\MyApp"
!macroend

用户/机器安装选择

禁用一键安装模式即可：

package.json:

"build": {
  "nsis": {
    "oneClick": false
  }
}

或electron-builder.yml:

nsis:
  oneClick: false

配置选项详解

electron-builder提供了丰富的NSIS配置选项，包括但不限于：

安装界面定制
快捷方式配置
安装模式设置
多语言支持
自定义安装逻辑
卸载行为控制

开发者应根据实际需求选择合适的配置组合，平衡用户体验和功能需求。

结语

electron-builder的NSIS支持为Electron应用提供了强大的Windows安装方案。通过合理配置，开发者可以创建专业级的安装体验，从简单的单文件安装到复杂的多架构Web安装都能轻松应对。掌握这些配置技巧将显著提升你的Electron应用分发质量。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考