⚡

macOS应用公证Skill asc-notarization

这个技能用于通过xcodebuild和asc工具对macOS应用进行归档、导出和公证，以便在App Store外分发，使用开发者ID签名和苹果公证。关键词：macOS、公证、开发者ID、签名、Xcode、苹果应用分发、asc工具。

其他 0 次安装 0 次浏览 更新于 3/13/2026

name: asc-notarization description: 使用 xcodebuild 和 asc 对 macOS 应用进行归档、导出和公证。适用于需要通过开发者 ID 签名和苹果公证为 App Store 外分发准备 macOS 应用的情况。

macOS 公证

当您需要对 macOS 应用进行公证以在 App Store 外分发时，使用此技能。

前提条件

  • Xcode 已安装且命令行工具已配置。
  • 认证已配置（asc auth login 或 ASC_* 环境变量）。
  • 本地钥匙串中有开发者 ID 应用证书。
  • 应用的 Xcode 项目为 macOS 构建。

预检：验证签名身份

归档前，确认有效的开发者 ID 应用身份存在：

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

如果未找到身份，请在 https://developer.apple.com/account/resources/certificates/add 创建（App Store Connect API 不支持创建开发者 ID 证书）。

修复损坏的信任设置

如果 codesign 或 xcodebuild 失败并提示“Invalid trust settings”或“errSecInternalComponent”，证书可能有自定义信任覆盖破坏链：

# 检查自定义信任设置
security dump-trust-settings 2>&1 | grep -A1 "Developer ID"

# 如果存在覆盖，导出证书并移除它们
security find-certificate -c "Developer ID Application" -p ~/Library/Keychains/login.keychain-db > /tmp/devid-cert.pem
security remove-trusted-cert /tmp/devid-cert.pem

验证证书链

修复信任设置后，验证链是否完整：

codesign --deep --force --options runtime --sign "Developer ID Application: YOUR NAME (TEAM_ID)" /path/to/any.app 2>&1

签名必须显示链：开发者 ID 应用 → 开发者 ID 认证机构 → 苹果根 CA。

步骤 1：归档

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

步骤 2：使用开发者 ID 导出

为开发者 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

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

验证导出

codesign -dvvv "/tmp/YourAppExport/YourApp.app" 2>&1 | grep -E "Authority|Timestamp"

确认：

  • 权限链以“Developer ID Application”开头
  • 存在时间戳

步骤 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 分发，在创建容器后装订：

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

支持的文件格式

格式 使用场景
.zip 最简单；压缩签名的 .app 包
.dmg 用于拖放安装的磁盘映像
.pkg 安装包（需要开发者 ID 安装器证书）

PKG 公证

要对 .pkg 文件进行公证，您需要 开发者 ID 安装器 证书（与开发者 ID 应用证书分开）。此证书类型不可通过 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”

开发者 ID 证书有自定义信任覆盖。参见上方的预检部分移除它们。

“The binary is not signed with a valid Developer ID certificate”

应用使用开发或 App Store 证书签名。使用 ExportOptions.plist 中的 method: developer-id 重新导出。

“The signature does not include a secure timestamp”

在手动 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 密钥。
  • 文件直接上传到苹果的 S3 桶，支持流式传输（无全文件缓冲）。
  • 超过 5 GB 的文件自动使用多部分上传。
  • 始终使用 --help 验证标志：asc notarization submit --help。