asc-notarization

macOS 公证

当你需要为在 App Store 之外分发的 macOS 应用进行公证时，请使用此技能。

前提条件

• 已安装 Xcode，并已配置命令行工具。
• 已配置身份验证（asc auth login 或 ASC_* 环境变量）。
• 本地钥匙串中有 Developer ID Application 证书。
• 应用的 Xcode 项目可针对 macOS 构建。

预检：验证签名身份

归档前，请确认存在有效的 Developer ID Application 身份：

security find-identity -v -p codesigning | grep "Developer ID Application"

如果找不到身份，请前往 https://developer.apple.com/account/resources/certificates/add 创建一个（App Store Connect API 不支持创建 Developer ID 证书）。

检查信任设置

如果 codesign 或 xcodebuild 因 "Invalid trust settings" 或 "errSecInternalComponent" 而失败，证书可能存在会破坏证书链的自定义信任覆盖：

# Check for custom trust settings
security dump-trust-settings 2>&1 | grep -A1 "Developer ID"

这些错误本身并不能证明原因是信任覆盖。在提出修复方案前，请检查受影响的证书。更改信任设置需要获得对该证书的明确授权；请勿移除信任覆盖，也不要为了诊断而对任意应用重新签名。

第 1 步：归档

xcodebuild archive \
  -scheme "YourMacScheme" \
  -configuration Release \
  -archivePath /tmp/YourApp.xcarchive \
  -destination "generic/platform=macOS"

第 2 步：使用 Developer ID 导出

为 Developer ID 分发创建 ExportOptions plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>developer-id</string>
    <key>signingStyle</key>
    <string>automatic</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
</dict>
</plist>

导出归档：

xcodebuild -exportArchive \
  -archivePath /tmp/YourApp.xcarchive \
  -exportPath /tmp/YourAppExport \
  -exportOptionsPlist ExportOptions.plist

这会生成一个使用 Developer ID Application 签名并带有安全时间戳的 .app 包。

验证导出结果

验证导出的应用现有签名和嵌套代码，然后显示其签名详情：

codesign --verify --deep --strict --verbose=2 "/tmp/YourAppExport/YourApp.app" && \
  codesign --display --verbose=4 "/tmp/YourAppExport/YourApp.app" 2>&1

确认：

• 验证命令成功退出；仅显示签名详情并不能验证签名
• Authority 链为 Developer ID Application → Developer ID Certification Authority → Apple Root CA，且 TeamIdentifier 符合预期
• 存在 Timestamp

如果验证失败或签名身份不符合预期，请在打包或上传前停止操作。诊断失败原因，并重新构建或重新导出预期的应用后再进行检查。这些检查不会修改软件包，也不能证明公证已获接受。

验证时不要添加 --sign 或 --force。Apple 的代码签名指南 区分了使用 --deep 进行递归验证和使用 --deep --force 进行签名；后者会强制重新签署嵌套代码。

第 3 步：创建用于公证的 ZIP

ditto -c -k --keepParent "/tmp/YourAppExport/YourApp.app" "/tmp/YourAppExport/YourApp.zip"

第 4 步：提交公证

提交后立即返回

asc notarization submit --file "/tmp/YourAppExport/YourApp.zip"

等待结果

asc notarization submit --file "/tmp/YourAppExport/YourApp.zip" --wait

自定义轮询

asc notarization submit --file "/tmp/YourAppExport/YourApp.zip" --wait --poll-interval 30s --timeout 1h

第 5 步：查看结果

状态

asc notarization status --id "SUBMISSION_ID" --output table

开发者日志（用于排查失败）

asc notarization log --id "SUBMISSION_ID"

获取日志 URL 以查看详细问题：

curl -sL "LOG_URL" | python3 -m json.tool

列出之前的提交

asc notarization list --output table
asc notarization list --limit 5 --output table

第 6 步：装订票据（可选）

公证成功后，装订票据以便应用在离线时也能运行：

xcrun stapler staple "/tmp/YourAppExport/YourApp.app"

对于 DMG 或 PKG 分发，请在创建容器后装订票据：

# Create DMG
hdiutil create -volname "YourApp" -srcfolder "/tmp/YourAppExport/YourApp.app" -ov -format UDZO "/tmp/YourApp.dmg"
xcrun stapler staple "/tmp/YourApp.dmg"

支持的文件格式

格式	用途
.zip	最简单；将已签名的 .app 包压缩为 ZIP
.dmg	用于拖放安装的磁盘映像
.pkg	安装器软件包（需要 Developer ID Installer 证书）

PKG 公证

若要为 .pkg 文件进行公证，你需要 Developer ID Installer 证书（与 Developer ID Application 证书不同）。App Store Connect API 不提供此类证书，请前往 https://developer.apple.com/account/resources/certificates/add 创建。

对软件包签名：

productsign --sign "Developer ID Installer: YOUR NAME (TEAM_ID)" unsigned.pkg signed.pkg

然后提交：

asc notarization submit --file signed.pkg --wait

故障排除

导出时出现 "Invalid trust settings"

自定义信任覆盖是可能的原因之一。请使用预检中的只读检查，找出受影响的证书，并在更改其信任设置前取得授权。

"The binary is not signed with a valid Developer ID certificate"

应用使用了 Development 或 App Store 证书进行签名。请在 ExportOptions.plist 中使用 method: developer-id 重新导出。

“签名不包含安全时间戳”

为手动调用 codesign 添加 --timestamp，或使用 xcodebuild -exportArchive，它会自动添加时间戳。

大文件上传超时

设置更长的上传超时时间：

ASC_UPLOAD_TIMEOUT=5m asc notarization submit --file ./LargeApp.zip --wait

公证返回“Invalid”，但签名看起来正确

获取开发者日志以查看具体问题：

asc notarization log --id "SUBMISSION_ID"

常见原因：未签名的嵌套二进制文件、缺少强化运行时、嵌入式库没有时间戳。

备注

• asc notarization 命令使用 Apple Notary API v2，而非 xcrun notarytool。
• 身份验证使用与其他 asc 命令相同的 API 密钥。
• 文件通过流式传输直接上传到 Apple 的 S3 存储桶（不会将整个文件缓冲到内存中）。
• 超过 5 GB 的文件会自动使用分段上传。
• 始终使用 --help 验证标志：asc notarization submit --help。