通过 asc cli 创建或续期 iOS/macOS…

在接入新应用、轮换签名资产或需要在团队间共享 iOS/macOS 签名证书和描述文件时，使用 asc cli 管理 Bundle ID、能力、证书、描述文件和加密同步。

适用场景

解决思路

1. 创建或查找 bundle ID：`asc bundle-ids list --paginate`；`asc bundle-ids create --identifier "com.example.app" --name "Example" --platform IOS`。
2. 配置 bundle ID capabilities：`asc bundle-ids capabilities list --bundle "BUNDLE_ID"`；`asc bundle-ids capabilities add --bundle "BUNDLE_ID" --capability ICLOUD`；需要时添加 capability settings：`--settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_6","enabled":true}]}]'`。
3. 对于 Developer Portal-only 的 `PRIVATE_CLOUD_COMPUTE` capability，使用用户拥有的 web session 和 Developer Portal Bundle ID resource ID：`asc web bundle-ids capabilities enable --bundle-id "BUNDLE_RESOURCE_ID" --capability PRIVATE_CLOUD_COMPUTE --confirm`；该 capability 不在公开 App Store Connect capability enum 中。如果缓存 session 无法访问 Developer Portal，清理其 scoped cache，然后用同一 binary 重新登录：`asc web auth logout --apple-id "user@example.com"`；`asc web auth login --apple-id "user@example.com"`。
4. 对于 App Groups，公开 API 可以启用 `APP_GROUPS`，但不能创建或关联 App Group 资源；使用 Account Holder 或 Admin web session：`asc web app-groups list --paginate --output table`；`asc web app-groups create --name "Example Shared" --identifier "group.com.example.app.shared" --confirm`；`asc web app-groups assign --group "GROUP_RESOURCE_ID" --bundle-id "BUNDLE_RESOURCE_ID" --confirm`；用 `asc web app-groups list` 解析 opaque group ID，用 `asc bundle-ids list` 解析 opaque Bundle ID resource ID；更改 assignment 会使包含该 App ID 的 provisioning profiles 失效，因此在下一次签名构建前重新生成受影响的 profiles。
5. 创建签名证书：`asc certificates list --certificate-type IOS_DISTRIBUTION`；`asc certificates create --certificate-type IOS_DISTRIBUTION --csr "./cert.csr"`；或内联生成 key 和 CSR：`asc certificates create --certificate-type IOS_DISTRIBUTION --generate-csr --key-out "./signing/dist.key" --csr-out "./signing/dist.csr"`。
6. 对于 Wallet passes，先创建 Pass Type ID，再创建其证书：`asc pass-type-ids create --identifier "pass.com.example" --name "Example Pass"`；`asc certificates create --certificate-type PASS_TYPE_ID --pass-type-id "PASS_TYPE_ID" --csr "./pass.csr"`；`asc pass-type-ids certificates list --pass-type-id "PASS_TYPE_ID" --paginate`。
7. 创建 provisioning profile：`asc profiles create --name "AppStore Profile" --profile-type IOS_APP_STORE --bundle "BUNDLE_ID" --certificate "CERT_ID"`；为 development/ad-hoc 包含设备：`asc profiles create --name "Dev Profile" --profile-type IOS_APP_DEVELOPMENT --bundle "BUNDLE_ID" --certificate "CERT_ID" --device "DEVICE_ID"`。
8. 下载 profile：`asc profiles download --id "PROFILE_ID" --output "./profiles/AppStore.mobileprovision"`。
9. 需要时本地检查并安装下载的 profile：`asc profiles inspect --path "./profiles/AppStore.mobileprovision" --output table`；`asc profiles inspect --path "./profiles/AppStore.mobileprovision" --entitlements --output markdown`；`asc profiles local install --path "./profiles/AppStore.mobileprovision"`；`asc profiles local list --output table`；在 macOS 上，默认目录跟随活动 Xcode：Xcode 16 或更新使用 `~/Library/Developer/Xcode/UserData/Provisioning Profiles`，Xcode 15 或更旧使用 `~/Library/MobileDevice/Provisioning Profiles`；没有完整活动 Xcode 的主机会回退到 legacy 目录并向 stderr 打印提示；当自动化必须指向固定目录时传 `--install-dir`。
10. 撤销旧证书：`asc certificates revoke --id "CERT_ID" --confirm`。
11. 删除或轮换前审计远程 provisioning profiles：`asc profiles list --profile-state ACTIVE,INVALID --paginate --output json`；Apple `profileState` 不是完整的过期信号：有些 profiles 可能有过去的 `expirationDate` 但仍报告 `ACTIVE`；对于真正的过期 profile 审计，比较 `expirationDate` 与当前日期，而不是只依赖 `INVALID`。
12. 删除旧 profiles：`asc profiles delete --id "PROFILE_ID" --confirm`。
13. 清理本地 Xcode provisioning profiles：`asc profiles local clean --expired --dry-run`；`asc profiles local clean --expired --confirm`；在确认前检查 dry-run 输出中解析出的目录，或用 `--install-dir` 固定它。
14. 使用 `asc signing sync` 做团队共享存储：当想要轻量、非交互式替代 fastlane match 的加密 git-backed certificate/profile 存储时使用；先保护 secret 输入：`chmod 600 "./signing-sync-password" "./distribution.p12" "./distribution-p12-password"`。
15. 推送可用 private identity 及其匹配 certificate 和 profile：`asc signing sync push --bundle-id "com.example.app" --profile-type IOS_APP_ADHOC --repo "git@github.com:team/certs.git" --password-file "./signing-sync-password" --identity "./distribution.p12" --identity-password-file "./distribution-p12-password" --output json`。
16. 拉取并解密到本地目录：`asc signing sync pull --repo "git@github.com:team/certs.git" --password-file "./signing-sync-password" --output-dir "./signing" --output json`。
17. `asc signing sync` 注意事项：App Store Connect 从不返回 private key；提供本地 PKCS#12 用 `--identity`，或使用 `--private-key` 配合 `--identity-sha256` 选择其匹配的 App Store Connect certificate；多 identity 的 PKCS#12 也需要 `--identity-sha256`。
18. `asc signing sync` 注意事项：优先使用 `--password-file`；`ASC_SIGNING_SYNC_PASSWORD` 是非文件 fallback；`--password` 在 5.0.0 中已移除并会被拒绝；`ASC_MATCH_PASSWORD` 不再读取，设置也会被忽略。
19. `asc signing sync` 注意事项：仅 certificate/profile sync 仍受支持，但会报告 `identityPresent: false`；它本身不是可用的签名 identity。
20. `asc signing sync` 注意事项：`pull` 会在 `sensitiveFiles` 中报告 private identities 并以 `0600` 模式写入；导入或使用拉取的 identity 仍是单独的显式步骤。
21. `asc signing sync` 注意事项：private identity sync 拒绝 `MAC_APP_DIRECT` 和 `MAC_CATALYST_APP_DIRECT`；仅 certificate/profile sync 仍可用。
22. Reconcile ad hoc devices and profiles：使用实验性 reconcile workflow，基于 Xcode archive 和受保护的 desired-devices 文件进行确定性、增量式更改：`asc signing reconcile plan --archive-path ".asc/artifacts/App.xcarchive" --devices-file ".asc/distribution/devices.json" --output json`；`asc signing reconcile apply --plan ".asc/distribution/signing/plan.json" --confirm --output json`。
23. Reconcile 限制：planning 不做 mutation，可能返回 `ready: false`；apply 可以注册缺失设备、创建安全 baseline App IDs、创建 successor ad hoc profiles；它从不删除或 patch 资源、启用 capabilities 或创建 certificates；在 `--confirm` 前审查 plan；当这些签名效果应绑定到端到端 distribution plan hash 时，使用 `asc-ad-hoc-distribution` skill。
24. 在 macOS 上用 ephemeral identity 运行单条命令，避免持久 login-keychain 和 profile 更改：`asc signing run --identity "./signing/App.p12" --identity-password-file "./signing/App-password" --profile "./signing/App.mobileprovision" --receipt ".asc/distribution/signing-run.json" -- xcodebuild -exportArchive -archivePath ".asc/artifacts/App.xcarchive" -exportPath ".asc/artifacts/release-testing" -exportOptionsPlist ".asc/ExportOptions.release-testing.plist"`。
25. `asc signing run` 行为：命令直接运行而不经过 shell，保留子进程 exit code，使用隔离的临时 keychain，并清理其临时 profile；它不打印成功数据，因此子进程拥有 stdout；绝不内联传递 identity passwords。
26. 始终检查 `--help` 获取确切的 enum 值（certificate types、profile types）。
27. 对大账户使用 `--paginate`。
28. 当需要多个证书时，`--certificate` 接受逗号分隔的 IDs。
29. 设备管理使用 `asc devices` 命令（需要 UDID）。
30. `asc profiles inspect` 和 `asc profiles local ...` 操作本地磁盘状态，不是 App Store Connect API 资源。

适用边界 · 注意事项

• 未安装并认证 asc cli（`asc auth login` 或 `ASC_*` 环境变量）时。
• 没有 Apple Developer/App Store Connect 账号、权限或不知道 bundle identifier 与目标平台时。
• 没有 CSR 文件且不允许 `asc certificates create --generate-csr` 生成时。