修复常见 iOS 签名错误

iOS 签名存在三个 Mac 签名没有的协调难题：

• Provisioning Profile 是服务器端状态。每一项权限（entitlement）、能力（capability）和设备列表都保存在 developer.apple.com 上，Xcode 在本地缓存一份副本。两者不一致时，构建会失败，而报错信息两个地方都不提。
• 自动签名试图帮你，但并不总能成功。它会替你创建 Profile、添加能力、注册设备——但前提是 Xcode 知道你指的是哪个团队。多团队账号在首次打开克隆下来的项目时，往往会触发"No account for team"错误。
• 能力需要在两处同时开启。一项能力必须同时在 developer.apple.com 的 App ID 上启用，并且在项目的权限文件（entitlements file）中声明。只开其中一处，就会产生两处都不提的报错。

模拟器完全免于上述所有限制——模拟器构建不需要签名或配置 Profile。如果你的项目在模拟器上构建成功，但在真机或上传时失败，那问题一定出在签名层，而不是代码本身。

追查任何签名错误之前，先证明构建本身是正常的。先在模拟器上跑一遍：

xcodebuild build \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -destination 'generic/platform=iOS Simulator'

如果这一步失败，问题在代码，不在签名——先把代码修好。如果成功，那么之后在真机上或 Archive 时出现的每一次失败，都是签名问题，下面的诊断表格适用。

这是首次克隆项目后最经典的报错：

error: No account for team "ABCDE12345". Add a new account in
Accounts settings or verify your selected team is correct.

这条报错并不是说该团队不存在，而是说你的 Xcode（以及 LingCode 调用 xcodebuild 时）没有登录任何隶属于该团队的 Apple ID。通常有三种情况会导致这个问题：

• 新机器，Xcode 里还没有添加 Apple ID。打开 Xcode > Settings > Accounts，添加你的 Apple ID，团队会自动出现。
• 有多个 Apple ID，但选错了。项目的 DEVELOPMENT_TEAM 固定到了某个团队 ID，而你当前的 Apple ID 属于另一个团队。要么修改项目的 DEVELOPMENT_TEAM，要么添加正确的 Apple ID。
• Apple ID 过期或双重认证会话失效。打开 Xcode > Settings > Accounts > 点击你的 Apple ID——团队列表为空或出现会话警告。重新验证身份即可。

不打开 Xcode 也能查到项目的 Team ID：

grep -A1 DEVELOPMENT_TEAM MyApp.xcodeproj/project.pbxproj | head -10

然后去 developer.apple.com/account 确认该团队确实在你的账号下。

两种签名模式，各有各的失败特征：

• 自动签名（Xcode > 项目 > Signing & Capabilities > "Automatically manage signing"）：Xcode 会在你添加能力或新增测试设备时自动创建和刷新 Provisioning Profile。本地开发很方便；但在 CI 环境中容易出问题，因为替你修改 developer.apple.com 所需的凭据很难以脚本方式提供。
• 手动签名：你按名称手动指定 Provisioning Profile 和签名证书。可重现、可脚本化，但每次能力变更都需要在开发者门户上重新生成 Profile 并下载。

务实的分工方式：本地开发用自动签名，Archive/发布用手动签名。可以在 Xcode > Signing & Capabilities 中按 Debug/Release 配置分别设置"Automatically manage signing"。命令行方式如下：

# 自动签名（开发）
xcodebuild build \
  -scheme MyApp \
  -destination 'generic/platform=iOS' \
  -allowProvisioningUpdates \
  CODE_SIGN_STYLE=Automatic \
  DEVELOPMENT_TEAM=ABCDE12345

# 手动签名（发布 / CI）
xcodebuild archive \
  -scheme MyApp \
  -archivePath build/MyApp.xcarchive \
  -destination 'generic/platform=iOS' \
  CODE_SIGN_STYLE=Manual \
  DEVELOPMENT_TEAM=ABCDE12345 \
  PROVISIONING_PROFILE_SPECIFIER="MyApp Distribution" \
  CODE_SIGN_IDENTITY="Apple Distribution: Your Name (ABCDE12345)"

-allowProvisioningUpdates 这个标志让 xcodebuild 能与 Apple 服务器通信以刷新 Profile。不加这个标志，CI 环境中的自动签名构建会报"no provisioning profile matches"。

一项能力需要在两处同时开启，两处必须保持一致：

• App ID，位于 developer.apple.com/account/resources/identifiers——能力复选框（推送通知、iCloud、Sign in with Apple、应用内购买、App Groups、Associated Domains 等）。
• 项目中的权限文件（通常是 MyApp.entitlements）——XML 键值对，与这些能力一一对应。

不一致时会出现的报错：

Provisioning profile "iOS Team Provisioning Profile: com.you.MyApp"
doesn't include the aps-environment entitlement.

这意味着你的权限文件声明了推送通知（aps-environment），但 developer.apple.com 上的 App ID 并未开启推送通知。解决方法：在门户上开启后重新生成 Profile，或者从项目里移除该权限声明。

The executable was signed with invalid entitlements. The
entitlements specified in your application's Code Signing
Entitlements file do not match those specified in your
provisioning profile.

根本原因相同，只是报错信息不同——权限文件与 Profile 不一致。修复顺序永远是：先在门户上改，再重新生成 Profile，再让 Xcode 拉取最新版本。

可以让 LingCode 帮你把已构建应用的当前权限导出来做一次核对：

codesign -d --entitlements - build/MyApp.app

以及查看 Provisioning Profile 实际授予了哪些权限：

security cms -D -i build/MyApp.app/embedded.mobileprovision

如果这两份输出的权限列表不一致，那就是问题所在。

这条报错有六种常见原因，按顺序逐一排查：

• Bundle ID 不匹配。项目中的 Bundle ID（PRODUCT_BUNDLE_IDENTIFIER）与门户上的 App ID 不一致，重命名后最常见。用 grep PRODUCT_BUNDLE_IDENTIFIER MyApp.xcodeproj/project.pbxproj 核对。
• Profile 类型与构建配置不符。Debug 构建需要 Development Profile，Archive 需要 Distribution Profile，不能混用。
• Profile 已过期。Profile 有效期一年，到期后在门户上重新生成并下载。
• 在 Xcode 中添加了能力但门户上没有同步（见步骤 4）。手动签名时会表现为 Profile 不匹配。
• 测试设备未注册。Development Profile 包含固定的设备列表，新设备需要将其 UDID 添加到门户后重新生成 Profile。
• 签名证书已过期或被吊销。Profile 绑定到特定证书，证书失效则 Profile 作废。重新签发证书后，再重新生成 Profile。

同一条报错信息可能对应以上六种情况中的任意一种，逐项排查，不要猜。

每次变更能力、轮换证书或添加设备后，Xcode 里缓存的 Profile 就已经过时了。修复方式每次都一样：

1. 前往 developer.apple.com/account/resources/profiles。
2. 找到对应的 Profile，点击 Edit，再点击 Save（这一步会根据当前 App ID 的状态重新生成 Profile）。
3. 下载新的 .mobileprovision 文件，双击安装到 Xcode 中。
4. 或者通过命令行：xcodebuild -allowProvisioningUpdates …，让 Xcode 自行拉取刷新后的 Profile。

漏掉门户上"Edit > Save"这一步，是重新下载后仍然报同样错误的最常见原因——门户在保存时触发重新生成，而不是在下载时。

如果 iOS Archive 出现 errSecInternalComponent，原因与 macOS 上相同：运行 xcodebuild（或 LingCode，或 CI worker）的进程没有获得完全磁盘访问权限，无法从 Keychain 读取签名密钥。这条报错与 Keychain 损坏的报错完全相同，所以很多人会追错方向。

解决方法：

• 系统设置 > 隐私与安全性 > 完全磁盘访问权限 > 添加 Terminal.app（或你的 CI Agent，或运行 LingCode 的宿主机）。
• 重启终端会话——TCC 授权不会对已运行的进程生效。
• 重试 Archive。

如果已经授权了完全磁盘访问但错误依旧，那才是 Keychain 本身的问题——打开 Keychain Access，找到签名证书，双击私钥，检查访问控制是否允许 codesign。

自动签名很好用，直到它不管用为止。以下情况建议切换到手动签名：

• 你需要可重现的 CI 构建。自动创建 Profile 需要 Apple ID 凭据，这类凭据不应该放进 CI 环境。
• 你使用的是开发者角色账号，Xcode 无法自动在门户上启用能力。手动签名让错误在操作门户时就暴露出来，而不是等到 Archive 才发现。
• 你有多个 Bundle ID（主应用 + 扩展 + WatchKit），Xcode 生成了互相重叠的 Profile。
• "No matching provisioning profile"已经折腾超过 30 分钟，反复重新生成和重试都没有解决。

手动签名用可见性换便利性——每一个错误都对应一个明确的门户操作，而不是 Xcode 黑盒式的自动协调。

将这个 skill 放入 LingCode 的 skills 文件夹，让 LingCode 帮你诊断任何 iOS 签名错误——它会替你走完整个诊断流程：

---
name: ios-signing-and-app-store
description: Use when shipping an iOS app to TestFlight or the App Store — Apple Developer enrollment, automatic signing, capabilities provisioning, archive, export, and notarytool/Transporter upload. Triggers: 'No account for team', 'No matching provisioning profile', 'TestFlight upload fails', 'App Store submission', 'iOS signing error', capability/entitlement sync failure, simulator-doesn't-need-signing baseline question, errSecInternalComponent during xcodebuild. Actions: prove simulator builds, pick automatic vs manual signing, fix entitlement drift, run notarytool, upload via Transporter. Errors: 'No account for team X', 'Capabilities X requires entitlement', expired profile, bundle ID mismatch. Skip if: just running on simulator.
---

Diagnose and fix iOS signing errors.

Step 0 — Prove the simulator builds clean. Simulator doesn't
sign; if simulator fails, the problem is code, not signing.

Step 1 — Resolve "No account for team": confirm the project's
DEVELOPMENT_TEAM matches an Apple ID added in Xcode > Settings >
Accounts. Re-auth on 2FA lapse.

Step 2 — Pick signing mode deliberately. Automatic for local dev
with -allowProvisioningUpdates. Manual for release/CI with
PROVISIONING_PROFILE_SPECIFIER and CODE_SIGN_IDENTITY pinned.

Step 3 — Capability/entitlement sync: a capability must be
enabled BOTH on the App ID at developer.apple.com AND in the
entitlements file. Verify with codesign -d --entitlements - and
security cms -D -i embedded.mobileprovision.

Step 4 — "No matching provisioning profile" walks six causes:
bundle ID mismatch, wrong profile type, expired profile,
unsynced capability, missing device, dead certificate.

Step 5 — After ANY portal change: Edit > Save the profile on
developer.apple.com (regenerates), then re-download or use
-allowProvisioningUpdates.

Step 6 — errSecInternalComponent = host process missing Full
Disk Access (same as macOS). Fix in System Settings, restart
terminal session.

Step 7 — Escalate to manual signing if automatic has failed
twice in a row.

保存为 ~/.lingcode/skills/ios-signing-and-app-store/SKILL.md——具体位置及 skill 的发现机制请参阅安装 Skill。

获取 LingCode →