Electron Builder 24.13.3版本中Mac应用公证问题的解决方案

问题背景

在Electron应用开发中，使用electron-builder工具打包Mac应用时，从24.12.0版本升级到24.13.3版本后，许多开发者遇到了公证(Notarize)流程失败的问题。错误信息通常表现为"无法解构未定义的options.appBundleId属性"或"使用密码凭证进行公证时需要teamId属性"。

问题分析

这个问题的根源在于electron-builder 24.13.3版本对Mac应用公证流程进行了重构，引入了更严格的参数验证和新的配置方式。主要变化包括：

1. 内置了自动公证功能，不再需要手动配置afterSign脚本
2. 对公证凭证的验证更加严格
3. 配置方式从环境变量为主转向了package.json配置为主

解决方案

方案一：使用环境变量配置

最简单的解决方案是通过环境变量配置公证参数：

export APPLE_ID=[e-mail]
export APPLE_APP_SPECIFIC_PASSWORD=your_app_specific_password
export APPLE_TEAM_ID=your_team_id

然后运行构建命令。这种方式不需要任何额外的package.json配置。

方案二：使用package.json配置

在package.json的build配置中添加notarize选项：

"build": {
  "mac": {
    "notarize": {
      "teamId": "YOUR_TEAM_ID"
    }
  }
}

同时仍然需要设置APPLE_ID和APPLE_APP_SPECIFIC_PASSWORD环境变量。

方案三：禁用内置公证并使用自定义脚本

如果你仍然希望使用自定义的afterSign脚本，可以显式禁用内置公证功能：

"build": {
  "mac": {
    "notarize": false
  },
  "afterSign": "./scripts/afterSign.js"
}

然后在afterSign.js中使用@electron/notarize包实现自定义公证逻辑。

最佳实践建议

1. 统一凭证管理：建议将公证凭证存储在.env文件中，而不是直接暴露在构建脚本中

2. 版本兼容性：升级electron-builder版本时，注意检查公证相关的变更日志

3. 错误处理：在CI/CD流程中添加公证失败的回退机制

4. 测试验证：在正式发布前，使用--skip-notarize参数测试构建流程

常见问题排查

1. 缺少teamId错误：确保APPLE_TEAM_ID环境变量或package.json中的teamId配置正确

2. 密码凭证错误：检查APPLE_APP_SPECIFIC_PASSWORD是否有效且未过期

3. 双重公证问题：如果同时配置了afterSign和内置公证，可能会导致重复公证

4. 超时问题：公证过程可能需要较长时间，适当增加构建超时限制

总结

electron-builder 24.13.3版本对Mac应用公证流程的改进虽然带来了一些兼容性问题，但也简化了大多数场景下的配置。开发者可以根据项目需求选择最适合的公证方案，确保应用能够顺利通过Apple的公证流程。

对于新项目，推荐使用内置的公证功能；对于已有项目，可以根据现有配置选择升级策略。无论采用哪种方式，都要确保凭证的安全性和配置的正确性。