构建工具桌面应用开发工具【免费下载链接】electron-builderA 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-builder v27 版本的速览指南v27 将整个生态迁移到原生 ES 模块Native ESM、将最低运行时提升到Node.js 22.12.0同时新增了 MSIX 目标、Cloudflare R2 发布、PKCS#11/HSM 代码签名等能力并静默调整了一批默认值。读完本文你将掌握 v27 的完整增量清单、那些migrate-schema无法替你处理的隐形行为变化以及如何用一条命令完成 v26 → v27 的配置迁移。v27 是一次主版本升级三个基调electron-builderv27是一次 major release它的基调可以概括为三点整个生态迁移到原生 ES Modules——每个包都以原生 ESM 形式发布得益于 Node.js 22.12.0 稳定化的require(esm)支持CJS 消费者无需改任何代码最低运行时提升到 Node.js 22.12.0——低于该版本直接构建失败硬删除自 v22 以来累积的废弃 API——不再保留兼容别名该删就删。对大多数项目而言升级只差两件事升级 Node.js 版本 运行一条迁移命令。build()API 和配置的运行时行为不变被重命名或重构的配置键由migrate-schema自动重写。正在升级存量项目运行electron-builder migrate-schema可自动应用配置键变更但下方「新默认值与行为变更」表格中的内容它是不会帮你处理的。有序升级步骤见 v26 → v27 迁移指南全部变更清单见 v27 Breaking Changes。v27 新增能力一览v27 的增量功能全部是纯加法additive设计——不迁移也能用旧行为不受影响。1. MSIX 目标betawin.target: msixv27 在 AppX 之外新增了 beta 版msixWindows 目标可产出.msix、.msixbundle多架构合并和.msixupload商店上传三类产物并支持 AppX 无法表达的现代 manifest 特性——Package Integrityuap10与Windows Servicesdesktop6。从源码结构看MsixTarget 独立实现了多架构上下文的记录与finishBuild阶段的 bundle 组装构建时按架构记录上下文结束时通过expandArtifactBeautyNamePattern(..., msixbundle, ...)/msixupload生成对应的合并产物文件名。win: target: msix # 无需 pin toolsets——默认的 winCodeSign 工具集已具备 MSIX 能力要点纯加法无需迁移与默认winCodeSign工具集开箱即用仅旧版0.0.0bundle 因缺少 MSIX 能力的 Windows SDK 而被拒绝MSIX 构建支持 Windows 10 原生环境macOS 上可通过 Parallels DesktopLinux 不支持MSIX不通过 electron-updater 自动更新——更新来自 Microsoft Store 或 App Installer完整配置面见 MSIX 目标文档。2. Cloudflare R2 发布 Providerprovider: r2v27 新增一个可选的provider: r2发布目标Cloudflare R2S3 兼容对象存储并配套了 electron-updater 支持。凭据来自CF_R2_ACCESS_KEY_ID/CF_R2_SECRET_ACCESS_KEY。从 r2Publisher.ts 的实现可以看到三类构建期校验bucket、accountId必填且accountId 必须是 32 位十六进制字符串正则/^[0-9a-f]{32}$/i校验用于在构建期拦截拼写错误而非上传时才报 DNS/连接错误publicUrl必须是合法 URL 且强制https:协议——它会被写进app-update.yml供终端用户的 electron-updater 下载更新元数据与二进制明文 http 被直接拒绝自动更新下载要求配置 CloudflareaccountId以及https 的publicUrl自定义域名或pub-hash.r2.dev子域名。3. Windows PKCS#11 与 HSM 代码签名betawin.sign两种新模式v27 为win.sign引入两个 beta 签名模式type: hsm——通过 signtool/csp /kc使用硬件安全模块HSM仅限 Windows。源码 hsmSignManager.ts 明确对非 Windows 平台抛出错误并提示macOS/Linux 请改用type: pkcs11要求toolsets.winCodeSign: 1.xtype: pkcs11——通过 osslsigncode 使用 PKCS#11 令牌跨平台可在 macOS/Linux CI 上直接签 Windows 应用无需 Windows 虚拟机。源码 pkcs11SignManager.ts 会校验pkcs11Module与pkcs11KeyUri必须同时设置并向 osslsigncode 传递-pkcs11module/-key参数。{ win: { sign: { type: pkcs11, pkcs11Module: /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so, pkcs11KeyUri: pkcs11:tokenMyToken;objectMyKey;typeprivate, certificateFile: cert.pem } }, toolsets: { winCodeSign: 1.3.0 } }两个模式均为beta接口已稳定但真实硬件上的测试覆盖有限。详细说明见 Windows 代码签名文档。4. DMGULMO/ LZMA 格式dmg.format: ULMOv27 为 DMG 新增dmg.format: ULMO——LZMA 压缩的磁盘镜像要求 macOS 10.15通常比默认的UDZO小约 30%。纯加法默认格式不变。详见 DMG 文档磁盘镜像格式。5. electron-updater 新增allowUnverifiedLinuxPackagesAppUpdater.allowUnverifiedLinuxPackages是一个新开关用于在安装.deb/.rpm自动更新时强制 GPG 签名校验。默认值为true保持历史宽松行为因为 electron-builder 本身并不对 Linux 包签名这是纯加法无需迁移。import { autoUpdater } from electron-updater autoUpdater.allowUnverifiedLinuxPackages false // 对 .deb/.rpm 更新强制 GPG 签名校验6. 新 CLI 命令migrate-schemav27 新增electron-builder migrate-schema命令就地重写你的配置为 v27 形态覆盖静态json/json5/yaml/package.json与程序化.js/.ts/.cjs/.mjs两类配置。electron-builder migrate-schema # 就地应用变更 electron-builder migrate-schema --dry-run # 仅预览不写入别名: -n从 migrate-schema.ts 源码看其迁移逻辑被刻意实现为纯函数migrateConfig(raw)无 I/O、可安全测试且键映射表由app-builder-lib持有并再导出——这样运行时守卫checkLegacyConfiguration与迁移器不会漂移。它覆盖的典型转换包括删除electronCompile、把原生模块选项归入nativeModules、合并 asar 子选项、snap→snapcraft重构、win.signtoolOptions/win.azureSignOptions→win.sign等。程序化配置则通过 migrate-schema-programmatic.ts 中的 AST 定位 codemod 重写保留注释、import、函数与格式。7. 原生 ESM Node.js 22.12每个包现在都以原生 ES 模块发布。在Node.js 22.12.0上import与 CJSrequire()均无需改代码即可使用// CJS require() — 仍然可用 const { build, Platform } require(electron-builder) // ESM import — 现在更推荐 import { build, Platform } from electron-builder如果你的项目使用type: module或 ESM import无需任何改动如果使用 CJS 且运行在 Node 22.12require()照常工作v27 包带exports映射和完整 TypeScript 声明moduleResolution的node旧式、node16/nodenext与bundler推荐全部可用。四个 Forge maker 插件electron-forge-maker-appimage、-nsis、-nsis-web、-snap同样转为原生 ESM但公开 API 不变——Electron Forge 通过内部动态import()加载它们无需改配置。新默认值与行为变更migrate-schema 管不到的部分以下运行时与默认值变更没有对应的配置键改名所以迁移器看不见它们。逐行扫一遍每行都深链到完整解释变更一句话影响详情Node.js 22.12.0 要求旧版 Node 上构建直接失败——升级本地运行时、CI 和 Docker 镜像→工具集解析为latest未设置 /null/latest现在拉取最新 bundleWine 11、winCodeSign 1.3.0、FUSE3 AppImage、NSIS 3.12pin0.0.0可恢复旧 bundle→每次构建都按 arch/os 过滤node_modulescpu/os与目标不匹配的依赖现在从应用中排除此前实际上仅对 universal-macOS 生效→arch: all→ x64 arm64all不再包含ia32——需显式请求ia32Electron 44 上 Windowsia32/ Linuxarmv7l快速失败→electron/electron-builder从node_modules中排除把它们列在dependencies中不再报错——而是从拷贝的node_modules中剔除可通过ignoredProductionDependencies调整集合→DMGfilesystem默认 APFS新镜像使用 APFS原为 HFS仅为兼容 10.13 之前的 macOS 才设置dmg.filesystem: HFS→disableWebInstaller默认trueelectron-updater 在 v27 警告、v28 阻断 NSIS web-installer 更新除非用disableWebInstaller: false显式开启→latest*.yml移除顶层path/sha512更新元数据只携带files[]读info.files[0]若仍提供 2.16 之前的 updater 则设置electronUpdaterCompatibility→无用户名的 Bitbucket token → Bearer 认证无用户名的BITBUCKET_TOKEN现按 Bearer 发送若是 app password / API token 请设置BITBUCKET_USERNAME→macOSproductName/executableName被校验需要文件名清洗的名称现在在构建开始时抛错而不再静默改写→NSIS 文件关联 ProgID 格式改变关联现在注册到唯一生成的 ProgID 下更新硬编码旧name/扩展名的自定义 NSIS 脚本→Linux.desktop运行*-launcher脚本每个 Linux 目标都通过生成的executableName-launcher启动.desktop的Exec指向它。更新自定义.desktop/ AppArmor / MIME 工具→AppImage 仅对旧 FUSE2 自动加--no-sandbox默认 FUSE3 运行时不再自动追加--no-sandbox需要无条件禁用沙箱时请设置executableArgs: [--no-sandbox]→Azure Trusted Signing 使用signtool /dlib默认 winCodeSign 1.3.0 内置 ATSdlib载荷ATS 自动走更快路径pin 到 1.3.0 以下可强制旧 PowerShell 路径→这是高频踩坑清单的简版。完整权威目录——包括迁移器会处理的配置键改名——见 v27 Breaking Changes。重点展开工具集默认值解析为latestv27 中每个toolsets.*属性默认值都是latest——未设置、null和字面量latest均解析为该工具集的最新发布 bundle此前各属性默认固定 pin 一个版本。无需改配置但有效默认值变了工具集v26 默认v27latest解析为升级涉及的内容wine0.0.0Wine 4.0.1仅 macOSsystem使用PATH上的主机安装 winemacOS 和 Linux 皆是。macOS 需要主机 Wine——见下方说明。pin1.0.1可下载 Wine 11.0 bundlemacOS arm64 走 RosettawinCodeSign0.0.0winCodeSign 2.6.01.3.0Windows Kits 10.0.26100.0osslsigncode2.11 原生 arm64内置 Azure Trusted Signingdlib .NET 8 运行时appimage0.0.0FUSE2 runtime1.1.0静态 FUSE3 兼容运行时无需宿主安装 FUSE新增unsquashfs支持nsis0.0.0NSIS 3.0.4.1拆分 bundle1.2.1NSIS 3.12统一单归档 bundle入口脚本自动设置NSISDIRfpm2.2.12.2.1不变——FPM 1.17.0 / Ruby 3.4.3icons1.1.01.2.1更新 bundle——wasm-vipsresvg/resvg-wasmlinuxToolsMac1.0.01.0.0不变——gnu-tar、lzip、binutils 等macOS → Linux 归档sevenZip1.0.01.0.0不变——唯一发布版本对大多数项目无需任何操作——新 bundle 是即插即用的替代品产物一致。wine是例外它的默认不再是一个 bundle因此 macOS 主机若构建 Windows 目标需要安装 Winebrew install --cask wine-stable或显式toolsets.wine: 1.0.1。若新版 bundle 引入回归可 pin 回0.0.0{ build: { toolsets: { winCodeSign: 0.0.0, nsis: 0.0.0, appimage: 0.0.0, wine: 0.0.0 } } }该逃生舱是短期方案0.0.0别名可能在未来的 major release 中移除。重点展开arch: all与 32 位构建arch: all不再包含ia32Platform.WINDOWS.createTarget(target, Arch.all)及等效的--arch all/ 默认多架构构建现在展开为x64 arm64Windows 和 Linux而非旧的 x64 ia32。Electron 44 移除了 Windowsia32构建Linuxia32zip 早在 Electron 19 就已终止旧展开在当前 Electron 上会产出损坏或不可能的构建。要继续构建 32 位请显式请求ia32如Arch.ia32或--ia32。Windowsia32/ Linuxarmv7l在 Electron 44 上快速失败请求这些架构并配合electronVersion 44已移除这些构建会在下载前抛出清晰的InvalidConfigurationError而不是死在晦涩的404上。配置了自定义electronDist或 Electron 镜像时降级为警告。Error: Electron 44.0.0 does not provide Windows ia32 builds — Electron 44 removed Windows ia32 and Linux armv7l support. Use electronVersion 43.x to keep building for ia32 (32-bit is supported until the v43 series reaches end-of-life in January 2027), or drop the ia32 target.行动项若仍提供 32 位 Windows/Linux 构建要么把electronVersionpin 到43.x或更早支持到 2027 年 1 月并显式请求ia32/armv7l要么放弃这些目标。重点展开node_modules每次构建按 arch/os 过滤v27 在每次构建时按各包package.json的cpu/os字段对照目标架构与平台过滤node_modules此前实际上只对universalmacOS 构建有意义。声明了与目标不兼容cpu/os的依赖会被排除出打包应用而 v26 是原样拷贝宿主安装的node_modules。典型项目无需操作——这修复了 universal 构建失败并产出正确的范围只有当你故意打包了一个跨架构/跨系统的可选二进制而现在被丢弃时才需要留意这种罕见情况下通过extraResources/files显式包含它。重点展开冗余生产依赖从报错变为排除v26 中把electron或electron-builder列在dependencies下会以硬InvalidConfigurationError中止构建。v27 改为把这些包从拷贝的node_modules中排除记一条日志并继续构建。它们对 SBOM、license、漏洞追踪等工具仍是合法生产依赖——electron-builder 只是换种方式提供它们Electron 运行时单独嵌入放进app.asar的拷贝是冗余的。排除集合通过新的ignoredProductionDependencies构建选项配置默认值为{ build: { ignoredProductionDependencies: [electron, electron-builder] } }覆盖该选项会替换默认列表所以除非有意打包它们请保留electron和electron-builder。典型用法添加名字排除不需要在node_modules拷贝的生产依赖。常见场景是打包器Vite、webpack、esbuild…已把包内联进应用代码——留在dependencies让 SBOM/license 工具可见同时加进这里避免重复打包{ build: { ignoredProductionDependencies: [electron, electron-builder, react, react-dom] } }移除名字保留该依赖在拷贝的node_modules中如从列表去掉electron-builder以把它打进应用。只有应用直接声明的依赖才可被排除通过 npm alias如custom-electron: npm:electron^30.0.0引入的依赖须按 alias 键名列在列表中。一个需要警惕的坑被保留的包在运行时require()了一个未声明的排除名依赖提升会以MODULE_NOT_FOUND崩溃——请在该需要的包中正确声明依赖或把名字移出列表。重点展开disableWebInstaller默认true与宽限期AppUpdater.disableWebInstaller现在默认true。NSISweb安装器安装时从 manifest 提供的 URL 下载完整载荷的小型安装器不再被默认加载因为该载荷可能未经签名校验。v27 提供一个主版本号的宽限期避免无警告地破坏存量部署从未设置disableWebInstaller默认收到 web-installer 更新时v27 记录警告并仍然下载。v28中警告升级为错误并阻断下载ERR_UPDATER_WEB_INSTALLER_DISABLED显式设置disableWebInstaller true立即抛出ERR_UPDATER_WEB_INSTALLER_DISABLED无宽限期不使用 web 安装器常见情况无需操作——这是更安全的默认v28 将强制执行。由 v27nsis-web构建产出的安装包自动 opt-inNSIS 安装器现在写入resources/package-type标记NsisUpdater读取它以把 web-installer 安装的disableWebInstaller默认设为false。所以下面的手动 opt-in 是给已在场外运行的应用v27 之前安装的而非新安装import { NsisUpdater } from electron-updater const updater new NsisUpdater() updater.disableWebInstaller false // 仅当你确实发布 web 安装器时提示对构建nsis-web目标的项目运行electron-builder migrate-schema会打印一条 advisory提醒你在运行时设置autoUpdater.disableWebInstaller false。该提示仅信息性——绝不改写你的配置disableWebInstaller是 electron-updater 运行时设置不是构建配置键。这条逻辑可以在 migrate-schema.ts 的NSIS_WEB_ADVISORY常量中直接看到。迁移路径三步走完整的升级路径见 v26 → v27 迁移指南核心三步Step 1运行自动化迁移器——electron-builder migrate-schema就地重写electron-builder.json、electron-builder.yml、package.jsonbuild 键等静态配置程序化配置.js/.ts/.cjs/.mjs通过 AST 定位的 codemod 重写保留注释、import、函数与格式。可用--config path指向非默认配置文件--project-dir dir指定项目根目录。迁移器自动处理的核心键映射包括electronCompile删除、npmSkipBuildFromSource→nativeModules.buildDependenciesFromSource、nativeRebuilder→nativeModules.rebuildMode、legacy asar 键 →asar.unpack/asar.disableSanityCheck/asar.disableIntegrity、macOS 签名字段 →mac.sign.*、signIgnore→sign.ignore、electronDownload→electronGet、GithubOptions.vPrefixedTagName→tagNamePrefix、win.azureSignOptions/win.signtoolOptions→win.sign、snap→snapcraft、helper-bundle-id→mac.helperBundleId、squirrelWindows.noMsi→msi取反、根级directories→build.directories等。序列化注意事项JSON5 → JSON重写.json5文件时产出合法 JSON无注释、标准引号并打印警告想保留注释就手动应用TOMLtoml包只读迁移器检测到 TOML 配置会打印所需变更并退出不写入YAMLjs-yaml往返保留键顺序但不保留注释程序化配置可归约为单个对象字面量时就地重写动态函数体、展开符、计算键或未安装typescript时回退为打印手动步骤snapbase 默认旧配置无base字段时工具假定core20v27 的 1-to-1 迁移目标并打印警告供确认。Step 2升级 Node.js 到 22.12.0——本地用nvm install 22 nvm use 22或fnmCI 中actions/setup-nodev4的node-version: 22Docker 用FROM node:22-bookworm-slimpackage.json声明engines: { node: 22.12.0 }。Step 3手动步骤——包括显式传--publish、替换devMetadata/extraMetadata为config.extraMetadata、% var %→${var}、更新硬编码旧 ProgID 的 NSIS 脚本、CI_BUILD_TAG→CI_COMMIT_TAG、用toolsets.X: { url, checksum }替换工具集环境变量覆盖等。源码级佐证与设计动机仓库源码为 v27 的多项变更提供了直接佐证迁移器实现migrate-schema.ts 的migrateConfig()是纯函数依次执行 electronCompile 删除、framework/nodeVersion/launchUiVersion删除、disableDefaultIgnoredFiles删除含 mac/mas/win/linux 各平台对象、linux.syncDesktopName删除若原为false则附警告、nativeModules 分组、asar 键合并、appImage.systemIntegration删除、publish 条目迁移、snap→snapcraft、helper-bundle-id→mac.helperBundleId、squirrelWindows.noMsi→msi等全程记录changes/warnings/advisories。MSIX 目标MsixTarget.ts 在finishBuild阶段按架构组装.msixbundle与.msixupload产物。R2 发布r2Publisher.ts 继承BaseS3Publisher实现providerName r2并对accountId、publicUrl做构建期校验。PKCS#11 / HSM 签名pkcs11SignManager.ts 限定 osslsigncode非 WindowshsmSignManager.ts 限定 Windows 的 signtool/csp /kc路径。从设计笔记看几个关键动机值得了解为什么原生 ESMelectron-builder 历史上发布 CommonJS。迁移由生态驱动chalk、figures、ora等主要依赖已放弃 CJS 支持Node.js 22.12 稳定化的require(esm)让发布 ESM 而不破坏 CJS 消费者成为安全操作。最低版本定为 22.12.0是因为更早的 Node 需要--experimental-require-module才能require()ESM 包。为什么统一 Windows 签名到win.signv26 中 Windows 签名拆在两个兄弟根级键signtoolOptions和azureSignOptions优先级规则易配错同时存在时 Azure 静默胜出。v27 用判别联合取代签名模式显式、IntelliSense 自文档化并与 macOS 的mac.sign形成同一心智模型win.sign: false哨兵显式禁用签名与未配置基于环境变量发现区分。为什么snap重构为snapcraft使base显式并把各 base 的选项嵌套在 base 命名的子键下单个配置可无歧义描述多个 basecore24直接使用 snapcraft CLI可与旧 base 共存。为什么PlatformPackager.info改为protected公开的info: Packager字段造成硬耦合任何内部Packager重构都会成为所有插件的破坏性变更。v27 为插件作者真正需要的属性添加了直通 getter并把info从public改为protected——外部packager.info.X访问不再可编译。小结升级前必查清单Node.js 运行时 22.12.0本地、CInode-version: 22、Docker 镜像运行electron-builder migrate-schema可先--dry-run预览发布脚本显式传--publish always|onTag|onTagOrDraft|never检查工具集默认wine现默认systemmacOS 需装 Wine 或 pin1.0.132 位构建arch: all不再含ia32Electron 44 上 ia32/armv7l 快速失败需要则 pinelectronVersion 43.xDMG默认 APFS仅兼容 10.13 之前的系统才设HFSelectron-updaterdisableWebInstaller默认truelatest*.yml只写files[]quitAndInstall改为对象参数autoInstallEvent替代autoInstallOnAppQuit生产依赖electron/electron-builder现在被排除而非报错用ignoredProductionDependencies调优插件/自定义目标作者packager.info.X与platformSpecificBuildOptions需改用新的直通 getter完整的权威变更目录含迁移器会处理的配置键改名、每个变更的 before/after 与设计理由见 v27 Breaking Changes有序升级步骤见 v26 → v27 迁移指南。赞分享构建工具桌面应用开发工具【免费下载链接】electron-builderA 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-builder v26 到 v27 迁移实战指南migrate-schema 自动迁移、Node.js 22.12 门槛与全部破坏性变更electron builder v26 到 v27 迁移实战指南migrate schema 自动迁移、Node.js 22.12 门槛与全部破坏性变更 v构建工具桌面应用开发工具electron-updater 安全默认值变更disableWebInstaller 在 electron-builder v27 中默认启用及 v28 迁移指南electron updater 安全默认值变更 disableWebInstaller 在 electron builder v27 中默认启用及 v28构建工具桌面应用开发工具electron-builder v27 重大变更arch: all 默认不再包含 ia32改为展开为 x64 arm64electron builder v27 重大变更 arch: all 默认不再包含 ia32改为展开为 x64 arm64 导读 本篇文章解读 e构建工具桌面应用开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考