RELEASE SETUP

安装 Developer ID 证书

用 Developer ID Application 签名、公证并直接分发 macOS App。证书必须与本机私钥配对；只有 `.cer` 文件不能完成签名。

需要 Apple Developer Program 适用于 macOS 14+ 不涉及 Mac App Store

BEFORE YOU START

确认 Team 权限

需要使用准备发布 App 的 Apple Developer Program Team。Account Holder 或 Admin 可以创建证书；其他角色需要 Team 开启 Access to Certificates, Identifiers & Profiles。

RECOMMENDED

通过 Xcode 安装

  1. 打开 Accounts进入 Xcode > Settings > Accounts，添加已加入开发者 Team 的 Apple ID。
  2. 选择 Team选中对应 Team，然后打开 Manage Certificates。
  3. 创建证书点击左下角 `+`，选择 Developer ID Application。
  4. 确认私钥Xcode 会在“登录”钥匙串中生成私钥并安装匹配的公开证书。

推荐这条路径，因为证书与私钥会在同一台 Mac 上自动正确配对。

MANUAL CSR

通过 Apple Developer 网站安装

Xcode 无法创建时，使用“钥匙串访问”手工生成 CSR：

  1. 生成 CSR打开“钥匙串访问”，选择 证书助理 > 从证书颁发机构请求证书。填写 Apple ID 邮箱和常用名称，选择“存储到磁盘”。
  2. 创建证书打开 Certificates, Identifiers & Profiles，选择 Developer ID Application 并上传 CSR。
  3. 导入证书下载 `.cer`，双击导入“登录”钥匙串。
  4. 展开检查在“钥匙串访问 > 我的证书”中展开证书，下面必须显示一把私钥。
不要只备份 `.cer`

`.cer` 不含私钥。若证书下面没有私钥，CSR 很可能在另一台 Mac 上生成，或本机私钥已经丢失。此时应重新创建 CSR 和证书。

VERIFY

在终端确认签名身份

identity
security find-identity -v -p codesigning

输出中必须出现有效的：

Developer ID Application: 名称 (TEAMID)

项目构建时，把这一整行传入 `COMPUTER_USE_CODESIGN_IDENTITY`。

NOTARIZATION

配置本机公证凭据

在 appleid.apple.com 创建 App 专用密码，然后交给 `notarytool` 存入钥匙串：

notary profile
xcrun notarytool store-credentials dsh-computer-use-notary \
  --apple-id 'release@example.com' \
  --team-id 'TEAMID' \
  --password 'app-specific-password'

构建并生成正式 DMG：

release
COMPUTER_USE_CODESIGN_IDENTITY='Developer ID Application: 名称 (TEAMID)' \
  pnpm run build

COMPUTER_USE_CODESIGN_IDENTITY='Developer ID Application: 名称 (TEAMID)' \
NOTARYTOOL_PROFILE='dsh-computer-use-notary' \
  pnpm run release:macos

GITHUB ACTIONS

导出 P12 与 API Key

在“钥匙串访问 > 我的证书”中右键 Developer ID 证书，导出为带强密码的 `.p12`。然后编码到剪贴板：

p12
base64 -i DeveloperIDApplication.p12 | pbcopy

在 App Store Connect > Users and Access > Integrations > App Store Connect API 创建 Team API Key，记录 Issuer ID 与 Key ID，并保存只能下载一次的 `.p8`。

MACOS_CERTIFICATE_P12Base64 编码的证书和私钥
MACOS_CERTIFICATE_PASSWORDP12 导出密码
MACOS_KEYCHAIN_PASSWORDCI 临时钥匙串密码
MACOS_CODESIGN_IDENTITY完整 Developer ID 身份
APPLE_API_KEY_IDApp Store Connect Key ID
APPLE_API_ISSUER_IDApp Store Connect Issuer ID
APPLE_API_KEY_P8P8 文件完整内容

TROUBLESHOOTING

常见问题

只有 Apple Development，没有 Developer ID Application
Apple Development 只适合本机开发验证。回到 Xcode Manage Certificates，使用已加入付费 Team 的账号创建 Developer ID Application。
证书存在，但 codesign 找不到 identity
在“我的证书”中确认它可以展开并显示私钥。没有私钥时不能签名。
证书显示不受信任
先更新 macOS/Xcode。仍有问题时，从 Apple PKI 页面安装最新 Developer ID 中间证书，并检查系统日期和钥匙串信任设置。
公证失败但签名通过
确认 Team ID、App 专用密码或 App Store Connect API Key 属于同一发布 Team，并读取 notarytool 返回的 submission log。