Electron应用上架前必做GitHub Actions自动化签名与公证的完整避坑指南当你花费数月时间开发了一款优秀的Electron应用却在最后一步——发布时遭遇系统拦截或用户安装失败这种挫败感足以让任何开发者崩溃。签名与公证不是可选项而是确保Mac用户能够顺利安装和使用你应用的必经之路。本文将带你深入理解这一流程的核心逻辑并通过GitHub Actions实现全自动化处理同时分享那些官方文档不会告诉你的实战经验。1. 为什么签名与公证如此重要在macOS生态中Gatekeeper机制会检查所有非App Store下载的应用是否来自可信来源。未签名或未公证的应用会被标记为已损坏或无法验证开发者导致用户无法直接打开。这不仅影响用户体验还可能让潜在用户对你的产品产生不信任感。签名(Signing)与公证(Notarization)的区别功能签名(Signing)公证(Notarization)主要目的验证应用来源扫描恶意行为执行者开发者Apple技术基础开发者ID证书Apple的自动化扫描系统用户可见效果显示开发者名称消除安全警告有效期证书有效期(通常1年)永久(除非应用变更)提示从macOS 10.15 Catalina开始公证成为强制要求。即使应用已签名未公证的应用仍会被系统阻止运行。2. 证书准备避开那些坑正确的证书类型是成功的第一步。很多开发者在这里栽跟头导致后续流程全部失败。2.1 选择正确的证书类型在Apple Developer后台你会看到多种证书选项但只有两种适用于Electron应用Developer ID Application- 用于签名应用本身(.app文件)Developer ID Installer- 用于签名安装包(.pkg文件)常见错误使用iOS开发证书或Mac Development证书进行签名这些证书仅用于开发测试不能用于分发。2.2 跨平台证书生成技巧如果你没有Mac设备可以通过Linux生成证书签名请求(CSR)# 生成私钥 openssl genrsa -out macos.key 2048 # 创建CSR文件 openssl req -new -sha256 -key macos.key -out macos.csr执行第二条命令时需要填写以下信息Country Name国家代码(如CN)State or Province Name省份全称(如Beijing)Locality Name城市名(如Beijing)Organization Name组织名(需与Apple Developer账号一致)Organizational Unit Name部门名称(可选)Common Name常用名(建议使用开发者邮箱)Email Address邮箱地址特别注意私钥密码必须妥善保存后续步骤会反复使用。3. 项目配置超越基础设置正确的工具链配置可以节省大量调试时间。以下是经过实战验证的最佳实践。3.1 必备依赖安装# 安装公证工具包 yarn add electron/notarize --dev # 环境变量管理 yarn add dotenv --dev3.2 公证脚本深度定制在scripts/notarize.js中我们需要实现公证逻辑const { notarize } require(electron/notarize); module.exports async (context) { if (process.platform ! darwin) return; const appPath ${context.appOutDir}/${context.packager.appInfo.productFilename}.app; await notarize({ appBundleId: com.yourcompany.app, // 必须与Info.plist中的CFBundleIdentifier一致 appPath: appPath, appleId: process.env.APPLE_ID, appleIdPassword: process.env.APPLE_APP_SPECIFIC_PASSWORD, teamId: process.env.APPLE_TEAM_ID // 关键避免公证失败 }); };常见问题排查错误Your Apple ID account is attached to other iTunes providers解决方案必须提供teamId参数可在Apple Developer账户的Membership页面找到错误Unable to notarize app检查应用是否已正确签名codesign -dv --verbose4 /path/to/YourApp.app4. GitHub Actions自动化全流程自动化是保证每次发布一致性的关键。以下配置经过数十个项目的验证。4.1 密钥安全存储在GitHub仓库的Settings Secrets中配置以下变量BUILD_CERTIFICATE_BASE64- 证书的Base64编码内容P12_PASSWORD- 私钥密码APPLE_ID- Apple开发者账号邮箱APPLE_APP_SPECIFIC_PASSWORD- 应用专用密码APPLE_TEAM_ID- 开发者团队ID注意应用专用密码需要在Apple ID账户页面生成不能直接使用账户密码。4.2 完整workflow配置name: Build and Notarize on: push: tags: [v*] env: ELECTRON_BUILDER_ALLOW_UNRESOLVED_DEPENDENCIES: true jobs: build: runs-on: macos-latest steps: - name: Checkout uses: actions/checkoutv3 - name: Setup Node uses: actions/setup-nodev3 with: node-version: 16 - name: Install Dependencies run: yarn install - name: Import Certificate run: | echo ${{ secrets.BUILD_CERTIFICATE_BASE64 }} | base64 --decode certificate.p12 security create-keychain -p temp build.keychain security import certificate.p12 -k build.keychain -P ${{ secrets.P12_PASSWORD }} -T /usr/bin/codesign security list-keychains -s build.keychain security default-keychain -s build.keychain security unlock-keychain -p temp build.keychain security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k temp build.keychain - name: Build App run: yarn build env: CSC_LINK: certificate.p12 CSC_KEY_PASSWORD: ${{ secrets.P12_PASSWORD }} APPLE_ID: ${{ secrets.APPLE_ID }} APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }} APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }} - name: Upload Artifacts uses: actions/upload-artifactv3 with: name: release path: dist/*关键点解析证书链处理创建临时钥匙串并导入证书避免影响系统默认钥匙串分区列表设置确保codesign能够访问钥匙串中的证书环境变量传递所有签名和公证所需参数都通过环境变量传递5. 高级调试技巧即使配置正确仍然可能遇到各种问题。以下是几个常见问题的解决方案。5.1 检查签名状态# 检查应用签名 codesign -dv --verbose4 YourApp.app # 检查安装包签名 pkgutil --check-signature YourApp.pkg有效签名应显示类似以下信息AuthorityDeveloper ID Application: Your Name (XXXXXXXXXX) AuthorityDeveloper ID Certification Authority AuthorityApple Root CA5.2 强制重新公证如果公证后应用仍有问题可以强制重新提交xcrun altool --notarize-app \ --primary-bundle-id com.yourcompany.app \ --username youremail.com \ --password keychain:AC_PASSWORD \ --file YourApp.zip5.3 查询公证历史xcrun altool --notarization-history 0 \ --username youremail.com \ --password keychain:AC_PASSWORD6. 多平台发布策略虽然本文聚焦Mac平台但实际项目中往往需要同时支持Windows和Linux。6.1 Windows签名注意事项需要购买代码签名证书(如DigiCert、Sectigo)使用signtool进行签名signtool sign /fd SHA256 /a /tr http://timestamp.digicert.com /td SHA256 /v YourApp.exe6.2 构建矩阵配置在GitHub Actions中可以通过构建矩阵实现多平台构建jobs: build: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-latest] runs-on: ${{ matrix.os }} steps: - name: Build run: yarn build if: matrix.os ! macos-latest env: CSC_LINK: ${{ secrets.WINDOWS_CERTIFICATE }} # 仅Windows需要在实际项目中我们遇到过因证书链不完整导致公证失败的情况。通过导出证书时包含完整链问题得以解决。另一个常见问题是时间戳服务不可用解决方案是配置备用时间戳服务器// electron-builder配置 win: { signingHashAlgorithms: [sha256], certificateFile: path/to/cert.pfx, certificatePassword: process.env.WINDOWS_CERT_PASSWORD, timestampServer: http://timestamp.sectigo.com }