Mac Electron 应用签名与公证全流程指南：从零到发布

1. 为什么Mac Electron应用需要签名和公证最近几年越来越多的开发者发现自己开发的Mac Electron应用在用户电脑上无法正常运行。最常见的情况是用户双击应用时系统弹出警告提示无法打开应用因为无法验证开发者。这种情况在macOS 10.14.5及更高版本中尤为常见。苹果从macOS 10.14.5开始引入了更严格的安全机制。简单来说所有在Mac上运行的应用程序都需要经过两道安全验证签名和公证。签名相当于开发者的数字身份证证明这个应用确实是你开发的公证则是把应用提交给苹果进行安全扫描确保应用不包含恶意代码。很多开发者尝试让用户通过终端命令sudo spctl --master-disable来绕过安全验证但这并不是个好办法。首先普通用户可能根本找不到终端在哪里其次让用户输入sudo命令存在安全风险最重要的是这种做法违背了苹果的安全设计初衷。正确的做法是老老实实走完签名和公证流程。2. 准备工作获取开发者账号和证书2.1 注册苹果开发者账号签名和公证都需要苹果开发者账号。如果你还没有账号需要先到苹果开发者网站注册。个人开发者账号年费是99美元公司账号也是同样的价格但需要提供额外的公司信息。注册完成后登录开发者账号进入Certificates, Identifiers Profiles页面。这里是我们后续操作的主要场所。2.2 创建证书签名请求(CSR)在生成开发者证书之前我们需要先在本地Mac上创建一个证书签名请求(CSR)文件打开钥匙串访问应用可以在Spotlight搜索顶部菜单选择钥匙串访问 证书助理 从证书颁发机构请求证书...填写你的邮箱地址建议使用开发者账号邮箱选择存储到磁盘点击继续保存为CertificateSigningRequest.certSigningRequest文件这个CSR文件包含了你的公钥信息苹果会用这个文件来验证你的身份。2.3 生成Developer ID Application证书现在回到苹果开发者网站进入Certificates页面点击按钮添加新证书选择Developer ID Application类型上传刚才生成的CSR文件下载生成的证书文件.cer格式下载完成后双击证书文件会自动安装到钥匙串中。在钥匙串访问应用中选择登录钥匙串然后在我的证书分类下就能看到新安装的证书。3. 应用签名全流程3.1 准备签名材料签名需要三个关键材料开发者证书上一步已经安装到钥匙串私钥生成CSR时自动创建应用标识符App Bundle Identifier首先我们需要把证书和私钥导出为.p12文件在钥匙串访问中找到你的开发者证书右键点击选择导出...选择.p12格式设置一个密码保存文件到安全位置3.2 配置Electron打包环境Electron应用的签名是在打包过程中完成的。我们需要配置一些环境变量export CSC_LINKfile:///path/to/your/certificate.p12 export CSC_KEY_PASSWORDyour_p12_password export APPLE_IDyour_apple_idemail.com export APPLE_ID_PASSWORDyour_app_specific_password注意APPLE_ID_PASSWORD不是你的Apple ID密码而是需要在苹果账号设置中生成的应用专用密码。3.3 使用electron-builder打包签名推荐使用electron-builder进行打包和签名。在package.json中添加如下配置build: { appId: com.yourcompany.yourapp, mac: { category: public.app-category.developer-tools, target: dmg, hardenedRuntime: true, gatekeeperAssess: false, entitlements: build/entitlements.mac.plist, entitlementsInherit: build/entitlements.mac.plist } }然后运行打包命令electron-builder --mac如果一切顺利你会在输出目录下看到签名后的.dmg或.pkg文件。可以通过以下命令验证签名是否成功codesign -dv --verbose4 /path/to/your.app4. 应用公证详细步骤4.1 公证工具变迁苹果的公证工具经历了多次变更。早期使用的是altool现在已经完全弃用。目前唯一支持的公证工具是notarytool它集成在Xcode命令行工具中。确保你已经安装了最新版Xcode命令行工具xcode-select --install4.2 提交公证申请使用以下命令提交公证申请xcrun notarytool submit YourApp.zip \ --apple-id your_apple_idemail.com \ --password your_app_specific_password \ --team-id your_team_id \ --wait参数说明YourApp.zip需要公证的应用包apple-id你的Apple IDpassword应用专用密码team-id可以在苹果开发者账号的Membership页面找到--wait等待公证完成可选4.3 检查公证状态提交后可以通过以下命令检查状态xcrun notarytool history \ --apple-id your_apple_idemail.com \ --password your_app_specific_password \ --team-id your_team_id公证通常需要5-30分钟。状态变化如下In Progress正在处理Accepted公证成功Invalid公证失败会提供失败原因4.4 处理公证失败如果公证失败可以通过以下命令查看详细日志xcrun notarytool log submission_id \ --apple-id your_apple_idemail.com \ --password your_app_specific_password \ --team-id your_team_id常见失败原因包括签名无效或不完整使用了过时的依赖库应用包含不允许的权限声明网络问题导致上传不完整5. 公证后的必要操作5.1 添加票据到应用公证成功后需要将公证票据(stapled ticket)附加到应用包上xcrun stapler staple YourApp.app这一步很重要它让应用在没有网络连接的情况下也能验证公证状态。5.2 最终验证完成所有步骤后建议进行完整验证spctl -a -v YourApp.app如果输出中包含accepted和notarized字样说明一切正常。5.3 分发应用现在你的应用可以分发给用户了。常见的分发方式包括直接提供.dmg或.pkg下载通过网站分发使用Sparkle等自动更新框架提交到Mac App Store需要额外的审核流程6. 常见问题与解决方案6.1 签名验证失败错误信息示例code object is not signed at all解决方案确认打包时确实执行了签名步骤检查CSC_LINK和CSC_KEY_PASSWORD环境变量设置正确尝试清理并重新打包rm -rf node_modules npm install npm run build6.2 公证被拒绝常见原因应用包含过时的依赖特别是原生模块权限声明(entitlements)配置不当解决方案更新所有依赖到最新版本检查entitlements.plist文件确保只声明必要的权限确保应用不尝试访问沙盒外的资源6.3 应用启动崩溃有时签名和公证都成功了但应用启动时崩溃。这通常是因为应用尝试访问受限资源如摄像头、麦克风但没有声明相应权限使用了不兼容的Electron版本原生模块没有正确签名调试方法查看系统日志console.app在终端中运行应用查看错误输出尝试禁用沙盒测试是否是权限问题7. 自动化与持续集成手动执行签名和公证流程很繁琐特别是需要频繁更新的应用。建议将流程自动化7.1 使用GitHub Actions示例workflow配置name: Build and Notarize on: push jobs: build: runs-on: macos-latest steps: - uses: actions/checkoutv2 - name: Install Node.js uses: actions/setup-nodev1 with: node-version: 14 - name: Install dependencies run: npm install - name: Build run: npm run build env: CSC_LINK: ${{ secrets.CSC_LINK }} CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }} APPLE_ID: ${{ secrets.APPLE_ID }} APPLE_ID_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }} TEAM_ID: ${{ secrets.TEAM_ID }} - name: Notarize run: | xcrun notarytool submit dist/*.zip \ --apple-id $APPLE_ID \ --password $APPLE_ID_PASSWORD \ --team-id $TEAM_ID \ --wait7.2 使用CircleCI类似地可以在CircleCI配置中添加签名和公证步骤。关键是确保CI环境能够访问证书文件和密码。8. 进阶技巧与最佳实践8.1 多架构支持随着Apple Silicon的普及建议同时支持x86_64和arm64架构build: { mac: { target: [dmg, zip], arch: [x64, arm64] } }8.2 加速公证流程公证通常需要等待以下方法可以加速尽量减小应用体积提前上传应用可以在最终构建前先传一个空壳使用--wait参数自动等待完成8.3 处理原生模块如果应用包含原生模块如node-sqlite3需要确保模块已经针对目标架构编译模块本身已正确签名在entitlements中声明必要的权限8.4 沙盒配置如果应用需要访问沙盒外资源需要仔细配置entitlements文件。示例?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keycom.apple.security.cs.allow-unsigned-executable-memory/key true/ keycom.apple.security.cs.disable-library-validation/key true/ keycom.apple.security.device.camera/key true/ keycom.apple.security.device.microphone/key true/ /dict /plist在实际项目中我发现最常遇到的问题往往与权限声明有关。特别是当应用需要访问摄像头、麦克风或者某些特殊目录时一定要在entitlements文件中明确声明。有一次我们花了整整两天时间排查一个启动崩溃问题最后发现只是因为忘记声明麦克风访问权限。