Electron Forge中Windows版本号处理问题解析

问题背景

在使用Electron Forge构建Windows平台应用安装包时，开发者可能会遇到一个棘手的问题：当应用程序版本号包含预发布标签（如"2.3.0-beta"）时，生成的MSI安装包安装后应用无法正常启动。这个问题特别容易出现在Windows 11 ARM架构设备上。

问题现象

当开发者在package.json中配置了包含预发布标签的版本号（如"2.3.0-foobar"）并使用@electron-forge/maker-wix制作Windows安装包时，构建过程中会显示警告信息："WiX distributables do not handle prerelease information in the app version, removing it from the MSI"。

安装后，应用程序目录会被命名为"app-2.3.0.0"这样的非标准SemVer格式，导致应用启动器无法正确识别和启动应用。直接运行应用主程序（如Asana-text.exe）可以正常工作，但通过启动器则失败。

技术分析

版本号处理机制

Electron Forge在构建过程中会对Windows平台的版本号进行特殊处理。核心问题出在Maker.ts文件中的normalizeWindowsVersion函数：

normalizeWindowsVersion(version: string): string {
  const noPrerelease = version.replace(/[-+].*/, '');
  return `${noPrerelease}.0`;
}

这个函数做了两件事：

1. 使用正则表达式移除预发布标签（"-"或"+"之后的内容）
2. 在版本号末尾强制添加".0"

问题根源

这种处理方式导致了三个技术问题：

1. SemVer兼容性问题：生成的版本号"2.3.0.0"不符合SemVer规范，导致启动器无法识别
2. 目录命名问题：应用安装目录基于这个非标准版本号命名，破坏了启动器的版本检测逻辑
3. 版本信息丢失：原始版本信息中的预发布标签被完全丢弃，无法在安装后恢复

相关组件交互

1. electron-wix-msi：实际负责MSI包生成的库，它本身已经具备处理SemVer版本号的能力
2. StubExecutable：启动器程序，它严格按照SemVer规范查找和启动应用
3. Windows Installer：要求版本号符合Windows特有的四段式格式（major.minor.build.revision）

解决方案

推荐方案

最简单的解决方案是修改Electron Forge的代码，移除强制添加".0"的逻辑。实际上，electron-wix-msi已经能够正确处理包含预发布标签的版本号，它会自动生成两个版本：

1. semanticVersion：保留原始SemVer版本（如"1.2.3-beta"），用于应用目录命名
2. windowsCompliantVersion：转换为Windows兼容格式（如"1.2.3.0"），用于MSI包

临时解决方案

开发者可以在forge.config.js中显式指定版本号，绕过自动处理逻辑：

const packageJSON = require('./package.json')

module.exports = {
  makers: [
    new MakerWix({
      version: packageJSON.version, // 显式传递原始版本号
    }),
  ],
}

最佳实践建议

1. 对于Windows平台构建，建议保持版本号简洁，尽量避免使用预发布标签
2. 如果必须使用预发布标签，确保构建系统正确处理版本号转换
3. 在跨平台开发中，统一版本号管理策略，减少平台差异带来的问题
4. 定期检查构建输出，验证安装目录结构和启动行为是否符合预期

总结

Electron Forge在Windows平台构建时对版本号的处理存在一定缺陷，特别是在处理预发布标签时。理解这一问题的技术背景和解决方案，有助于开发者构建更可靠的Windows应用安装包。随着Electron生态的不断发展，这类平台兼容性问题有望得到进一步改善。