macOS 代码签名

口径说明

融云公开文档不覆盖 macOS 原生 SDK 与桌面交付链（dmg / 代码签名 / 公证 / 分发 / Gatekeeper）；本页为本项目按 Apple 与 Electron 官方实践补齐的接入文档。

macOS 用代码签名标识“这个应用是谁发布的、包内容有没有被改过”。本地开发验证可用 ad-hoc 签名；对外分发必须用 Developer ID Application 证书，并配合公证（notarization）才能通过 Gatekeeper。

两种签名方式​

方式适用命令Gatekeeper
ad-hoc本地开发 / 内部测试（不对外分发）`codesign --force --deep --sign - "App.app"`本机可运行；其它机器仍提示未验证
Developer ID对外分发electron-builder 自动调用 `codesign`，或用 `codesign --sign "Developer ID Application: ..."`签名 + 公证后通过

ad-hoc 签名（本地验证）​

Shell
# electron-builder 产出后，做一次 ad-hoc 签名
codesign --force --deep --sign - "dist/mac/My Desktop.app"

# 验证
codesign -dv --verbose=4 "dist/mac/My Desktop.app"
codesign --verify --deep --strict --verbose=2 "dist/mac/My Desktop.app"

ad-hoc 签名只保证包内一致性，不提供发布者身份；换机器或重新下载后仍会被 Gatekeeper 拦截，属于预期。

Developer ID 签名（对外分发）​

Shell
# 1) 确认证书已安装（钥匙串 → 我的证书）
security find-identity -v -p codesigning

# 2) 导出 .p12 并在 CI 中以环境变量提供（不要提交到仓库）
#    CSC_LINK=file:///path/to/developer-id.p12
#    CSC_KEY_PASSWORD=********

# 3) electron-builder 签名 + 公证（公证见下一页）
CSC_LINK="$PWD/certs/developer-id.p12" \
CSC_KEY_PASSWORD="$CSC_KEY_PASSWORD" \
npx electron-builder --mac --x64 --arm64

签名参数说明​

参数作用建议
`--options runtime`启用 hardened runtime（公证前置条件）发布包必须开启
`--entitlements build/entitlements.mac.plist`声明 JIT / 网络等能力最小权限，逐项确认
`--deep`递归签名嵌套 framework / helperelectron-builder 默认处理；手动签名时使用
`--timestamp`签名附可信时间戳发布包必须；避免证书过期后签名失效
`--sign -`ad-hoc 签名仅本地验证

验证签名​

Shell
codesign -dv --verbose=4 "dist/mac/My Desktop.app"           # Authority / TeamIdentifier / flags
codesign --verify --deep --strict --verbose=2 "dist/mac/My Desktop.app"
spctl -a -vvv "dist/mac/My Desktop.app"                        # 公证后应为 accepted

# 查看嵌套组件签名
codesign -dv --verbose=4 "dist/mac/My Desktop.app/Contents/Frameworks/Electron Framework.framework"

常见问题​

报错原因处理
`code object is not signed at all`嵌套 framework 未签名用 `--deep` 或让 electron-builder 统一签名
`errSecInternalComponent`钥匙串未解锁 / 权限不足`security unlock-keychain`，CI 中先导入证书
`invalid signature (code or signature have been modified)`签名后修改了包内容重新打包并重新签名
`resource fork, Finder information, or similar detritus not allowed`包内残留扩展属性`xattr -cr "App.app"` 后重新签名