Electron 打包成 macOS dmg 后 Gatekeeper 拦截怎么解决

正式分发给用户时，必须通过苹果开发者账号进行代码签名并公证（Notarization），这是唯一能避免 Gatekeeper 拦截的合规方案；本地调试则可以通过清除 quarantine 属性临时绕过。

核心结论：生产环境必须走签名 + 公证流程，本地测试可用命令清除隔离属性。

适用场景：Electron 应用在 macOS 上分发或本地调试
前置准备：苹果开发者账号（生产）或终端权限（本地）
验收标准：spctl 验证签名状态及公证票据

本地调试：临时绕过拦截

开发阶段若未签名，macOS 会标记文件为隔离状态。仅限本机测试使用，严禁分发给用户。

xattr -cr /Applications/YourApp.app

若仍提示“已损坏”，尝试强制清除 quarantine 属性：

sudo xattr -rd com.apple.quarantine /Applications/YourApp.app

风险提示：此操作会降低系统安全性，仅用于开发验证，勿用于生产包。

生产环境：签名与公证流程

正式分发需加入 Apple Developer Program 获取 Developer ID 证书。推荐使用 electron-builder（v20+ 版本支持内置公证）。

1. 配置构建参数

在 package.json 或 electron-builder.yml 中配置签名信息。注意：敏感信息不要明文写入配置文件。

"mac": {
  "identity": "Developer ID Application: Your Name",
  "hardenedRuntime": true,
  "gatekeeperAssess": false,
  "entitlements": "build/entitlements.mac.plist",
  "entitlementsInherit": "build/entitlements.mac.plist",
  "notarize": {
    "teamId": "YOUR_TEAM_ID"
  }
}

2. 设置环境变量（关键）

公证所需的 Apple ID 和密码应通过环境变量传递，避免泄露。生成专用密码需访问 appleid.apple.com。

export APPLE_ID="your_email@example.com"
export APPLE_APP_SPECIFIC_PASSWORD="xxx-xxx-xxx-xxx"
export CSC_LINK="$(openssl base64 -in certificate.p12)"
export CSC_KEY_PASSWORD="your_p12_password"

3. 执行构建

配置完成后，运行构建命令。electron-builder 会自动完成签名、提交公证及 Staple 票据。

npm run build
# 或
npx electron-builder -m

CI/CD 环境注意事项

在自动化流水线中，需确保钥匙串已解锁且私钥可访问。

security unlock-keychain -p "keychain_password" login.keychain-db
# 确保构建用户有权限访问私钥

验证与排查

构建完成后，务必验证签名和公证状态。

1. 检查签名状态：

Electron 打包成 macOS dmg 后 Gatekeeper 拦截怎么解决

spctl `--assess` -vvvv `--type` install /Applications/YourApp.app

输出包含 accepted 表示通过。

2. 检查公证票据：

xcrun stapler validate /Applications/YourApp.app

若显示 The staple and validate action worked! 则票据已正确绑定。

常见坑与解决方案

1. Hardened Runtime 未开启

公证必须开启 Hardened Runtime，否则提交会被拒绝。配置中需显式设置 "hardenedRuntime": true。

2. 钥匙串权限拒绝

签名时若弹窗要求输入钥匙串密码，CI/CD 环境会卡住。需提前导入证书并设置“始终允许”或使用 security 命令解锁。

3. 忘记 Staple 票据

公证成功后未 Staple 票据，用户离线安装会被拦截。electron-builder 通常自动处理，若手动构建需执行 xcrun stapler staple。

4. 敏感信息泄露

切勿将 Apple ID 密码或 p12 密码提交至 Git 仓库。建议使用 .env 文件并加入 .gitignore。

参考来源

Apple Developer - Notarizing macOS software before distribution
electron-builder - Code Signing