Electron-Builder 中 Notarize 工具 JSON 解析错误的解决方案

在 Electron 应用打包过程中，开发者经常会遇到 macOS 应用公证（Notarization）的问题。近期，Electron-Builder 用户在使用 notarytool 进行公证时遇到了一个典型的 JSON 解析错误，表现为 "Unexpected token 'E', 'Error: The'... is not valid JSON"。本文将深入分析这个问题并提供多种解决方案。

问题背景

当开发者使用 Electron-Builder 24.13.3 及以上版本进行 macOS 应用公证时，可能会遇到以下错误信息：

Unexpected token 'E', "Error: The"... is not valid JSON

这个错误通常发生在 notarytool 尝试解析 Apple 公证服务返回的响应时。错误信息表明，工具期望接收 JSON 格式的响应，但实际上收到了以 "Error:" 开头的文本响应。

根本原因分析

经过开发者社区的调查，发现这个问题主要有以下几个潜在原因：

1. Apple 开发者协议未更新：Apple 有时会更新开发者协议，需要开发者手动接受新条款才能继续使用公证服务。

2. 环境变量命名问题：Electron-Builder 的自动公证功能要求环境变量使用特定格式（如 APPLE_API_KEY），而 @electron/notarize 包则期望使用驼峰式命名（如 appleApiKey）。

3. 认证信息错误或缺失：API 密钥、密钥 ID 或颁发者信息不正确或未正确设置。

4. 版本兼容性问题：某些 Electron-Builder 版本与 @electron/notarize 版本存在兼容性问题。

解决方案

1. 检查并接受 Apple 开发者协议

许多开发者发现，登录 Apple 开发者账户并接受最新的开发者协议可以解决此问题。这是最常见的解决方案之一。

2. 降级 Electron-Builder 版本

将 Electron-Builder 降级到 24.9.1 版本可以获取更详细的错误信息，帮助诊断问题：

npm install electron-builder@24.9.1

降级后，你可能会看到更明确的错误信息，如 "HTTP status code: 403. A required agreement is missing or has expired"。

3. 明确指定公证配置

在 electron-builder.yml 或 package.json 中明确指定公证配置，而不是依赖自动检测：

afterSign: ./notarize.js

然后创建一个 notarize.js 文件，使用 @electron/notarize 包进行公证：

const { notarize } = require('@electron/notarize');

exports.default = async function notarizing(context) {
  const { electronPlatformName, appOutDir } = context;
  if (electronPlatformName !== 'darwin') return;

  const appName = context.packager.appInfo.productFilename;
  
  return await notarize({
    appBundleId: 'com.yourcompany.yourapp',
    appPath: `${appOutDir}/${appName}.app`,
    appleId: process.env.APPLE_ID,
    appleIdPassword: process.env.APPLE_PASSWORD,
  });
};

4. 使用 resolutions 固定 @electron/notarize 版本

在 package.json 中添加 resolutions 字段，固定 @electron/notarize 版本：

"resolutions": {
  "@electron/notarize": "2.3.2"
}

5. 升级到 Electron-Builder 的 next 版本

Electron-Builder 的 next 版本已经包含了最新的 @electron/notarize 2.3.2，可以尝试升级：

npm install electron-builder@next

最佳实践建议

1. 始终检查 Apple 开发者账户：在遇到公证问题时，首先检查是否有待接受的开发者协议。

2. 使用明确的配置：避免依赖自动检测，明确指定公证配置可以减少不确定性。

3. 保持依赖更新：定期更新 Electron-Builder 和 @electron/notarize 到最新稳定版本。

4. 实施完善的错误处理：在构建脚本中添加适当的错误处理和日志记录，以便快速诊断问题。

5. 考虑 CI/CD 环境：在持续集成环境中，确保所有必要的环境变量都已正确设置，并且构建机器可以访问 Apple 的公证服务。

总结

Electron-Builder 的公证过程可能会因为多种原因出现问题，但通过系统性的排查和适当的解决方案，大多数问题都可以得到解决。开发者应该关注错误信息的细节，理解公证流程的各个环节，并保持开发环境的更新和一致性。随着 Electron 生态系统的不断发展，这类问题通常会随着新版本的发布而得到改善。