快速解决 command codesign failed with a nonzero exit code 问题 – wiki基地

作者： /

终结困扰：深度解析与彻底解决 Xcode 中的 “command codesign failed with a nonzero exit code” 错误

作为 iOS 或 macOS 开发者，您可能在进行应用构建或归档（Archive）时，遇到过一个令人沮丧且常见的错误提示：command codesign failed with a nonzero exit code。这个错误就像一个拦路虎，阻止您的应用成功签名，从而无法在设备上运行、进行测试，更不用说发布到 App Store。它可能突然出现，有时没有任何明显的原因，让许多开发者感到困惑和无助。

本文将深入剖析这个错误产生的根本原因，并提供一系列详细、系统的故障排除步骤，帮助您彻底解决这一问题，夺回构建过程的控制权。我们的目标不仅仅是提供解决方案，更是帮助您理解代码签名机制，从而能够更高效地诊断和预防这类问题。

理解代码签名：为何它如此重要？

在深入故障排除之前，了解“代码签名”（Code Signing）的意义至关重要。在 Apple 的生态系统中，代码签名是安全性和信任的基础。它的主要作用包括：

  1. 验证身份： 确保应用的开发者是经过 Apple 认证的。
  2. 保证完整性： 确认应用自签名以来没有被第三方篡改或损坏。
  3. 控制权限： 配合 Provisioning Profile（配置文件），限制应用只能在特定的设备上运行，或具备特定的功能（如 Push Notifications, iCloud, App Groups 等）。
  4. 发布与分发： 只有正确签名的应用才能通过 App Store 分发，或以 Ad Hoc、Enterprise 方式安装到设备上。

当 command codesign failed 错误发生时，意味着 Xcode 在尝试使用 codesign 工具对您的应用 bundle（如 .app 文件）进行数字签名时失败了。这个失败可能源于签名所需的任何一个环节出现问题。

“command codesign failed” 错误产生的常见原因

这个错误通常不是由单一原因引起，而是多种因素的叠加或组合。最常见的原因包括：

  • 证书（Certificates）问题： 证书过期、丢失、无效，或者与之配对的私钥缺失。
  • 描述文件（Provisioning Profiles）问题： 描述文件过期、无效、损坏，或与证书、App ID、设备不匹配。
  • App ID（Bundle Identifier）问题： 项目的 Bundle Identifier 与描述文件中的 App ID 不匹配。
  • 钥匙串访问（Keychain Access）问题： 签名所需的私钥在钥匙串中不可用、权限设置不正确，或钥匙串本身出现问题。
  • 项目配置（Build Settings）问题： Xcode 项目的签名设置（Code Signing Identity, Provisioning Profile）配置错误或不一致。
  • 能力项（Capabilities）问题： 项目启用的能力项（如 Push Notifications, App Groups）与 App ID 或描述文件中配置的不符。
  • 第三方库/框架问题： 项目集成的第三方库、SDK 或嵌入式框架（Embedded Frameworks）的签名问题。
  • Xcode 或系统问题： Xcode 的缓存损坏、软件 bug，或者 macOS 系统本身的问题。

接下来，我们将针对这些常见原因，提供详细的故障排除步骤。

系统化故障排除步骤：从简单到复杂

解决 command codesign failed 错误需要采取系统性的方法，从最简单、最常见的原因开始排查。请按照以下步骤逐步进行：

步骤 1：执行基础清理和重启

这是最简单但通常非常有效的第一步，可以解决很多由缓存或临时文件引起的问题。

  1. 清理构建文件夹（Clean Build Folder）：
    • 在 Xcode 菜单栏中选择 Product -> Clean Build Folder (或者按下快捷键 Shift + Command + K)。
    • 这个操作会删除之前构建生成的中间文件和缓存，迫使 Xcode 在下次构建时重新生成一切。这是解决因构建缓存损坏导致签名问题的常用方法。
  2. 重启 Xcode：
    • 彻底退出 Xcode 应用，然后重新打开您的项目。
    • 有时候，Xcode 内部的状态可能会变得不稳定，简单的重启就能恢复正常。
  3. 重启您的 Mac：
    • 这是最后的杀手锏，可以解决一些系统层面或后台进程可能导致的签名问题。
    • 确保在重启前保存所有工作。

尝试构建项目，看问题是否解决。如果问题依然存在，继续下一步。

步骤 2：检查 Apple 开发者账户状态

证书和描述文件是签名的核心。确保它们在 Apple 开发者账户中处于有效状态。

  1. 登录 Apple Developer 网站：
    • 访问 developer.apple.com 并使用您的 Apple ID 登录。
  2. 检查证书 (Certificates)：
    • 导航到 Certificates, Identifiers & Profiles。
    • 点击 Certificates。
    • 查看您用于签名的开发者证书 (Apple Development) 和分发证书 (Apple Distribution)。
    • 检查有效期： 它们是否已经过期？过期的证书无法用于签名。如果过期，您需要生成新的证书。
    • 检查状态： 状态是否是 Valid？如果是 Revoked (已撤销)，则无法使用。如果被撤销，您需要生成新的证书。
    • 每年限制： 注意每种类型的证书每年有数量限制（通常是2个）。确保您没有超出限制。
  3. 检查标识符 (Identifiers – App IDs)：
    • 导航到 Identifiers。
    • 找到与您的应用 Bundle Identifier 相对应的 App ID。
    • 检查类型： 是 Explicit App ID (特定 Bundle ID) 还是 Wildcard App ID (通配符)？
    • 检查能力项： 确保 App ID 中启用的能力项（如 Push Notifications, App Groups, Associated Domains 等）与您的项目实际使用的能力项一致。如果您在项目中启用了新的能力项，需要在这里编辑 App ID 并启用对应的服务。
  4. 检查描述文件 (Provisioning Profiles)：
    • 导航到 Profiles。
    • 找到您在 Xcode 项目中使用的描述文件（开发用通常是 iOS App Development，分发用通常是 App Store 或 Ad Hoc）。
    • 检查有效期： 描述文件是否已经过期？描述文件的有效期也有限制（通常是1年）。
    • 检查状态： 状态是否是 Valid？如果显示为 Invalid (无效)，通常是因为关联的证书过期、关联的 App ID 能力项发生变化、或者关联的设备列表发生变化（对于开发/Ad Hoc 配置文件）。
    • 检查包含内容：
      • 对于开发/Ad Hoc 描述文件，检查它是否包含了您用于签名的有效证书，以及您想要安装应用的设备的 UDID。
      • 检查它是否关联了正确的 App ID。
      • 检查它是否包含了正确的 Entitlements（能力项）。
    • 如果无效或过期： 需要编辑该描述文件（如果是因为设备列表变化或能力项变化），或生成一个新的描述文件（如果是因为证书过期或描述文件本身过期）。

重要提示： 在 Apple Developer 网站上对证书、App ID 或描述文件进行任何修改或重新生成后，您需要将这些更新下载到您的 Mac 上，并确保 Xcode 能够识别它们。最简单的方法是：

  • 下载更新后的描述文件 (.mobileprovision 文件)，双击安装。或者直接拖拽到 Xcode 的 Dock 图标上。
  • 下载新的证书文件 (.cer 文件)，双击安装到钥匙串中。但通常更推荐通过 Xcode 自动管理或直接在开发者网站生成 P12 文件导出导入。

您可以在 Xcode 中检查已安装的描述文件：Xcode -> Preferences -> Accounts -> 选择您的 Apple ID -> Download Manual Profiles。确保您需要的、最新的描述文件出现在列表中。

如果问题依然存在，继续下一步。

3. 深入检查钥匙串访问 (Keychain Access)

钥匙串访问是存储您的证书和私钥的地方。codesign 工具需要从这里获取私钥来完成签名过程。

  1. 打开钥匙串访问：
    • 打开 访达 (Finder) -> 应用程序 (Applications) -> 实用工具 (Utilities) -> 钥匙串访问 (Keychain Access)。
  2. 选择钥匙串和分类：
    • 在左侧导航栏的 钥匙串 下，选择 登录 或 System (根据您的证书存储位置，通常在 登录 下)。
    • 在 分类 下，选择 我的证书 (My Certificates)。这是查看证书和与之配对的私钥最方便的地方。
  3. 查找您的签名证书和私钥：
    • 查找您的开发者证书 (Apple Development: Your Name (Team ID)) 或分发证书 (Apple Distribution: Your Name (Team ID))。
    • 重要检查： 在证书名称下方，是否有一个展开箭头 (> 或三角形)？点击它。展开后，您应该能看到与之配对的私钥。私钥的图标是一个钥匙。如果看不到私钥，或者私钥显示为灰色/无效，这就是签名失败的常见原因！
      • 原因： 没有私钥，codesign 无法用您的身份对应用进行加密签名。
      • 解决： 如果您是在另一台 Mac 上生成的证书，您需要从那台 Mac 上导出证书和私钥 (.p12 文件)，然后导入到当前 Mac 的钥匙串中。如果在当前 Mac 上生成证书时没有自动生成私钥（极少见），或者私钥丢失/损坏，您可能需要撤销旧证书并在 Apple Developer 网站上重新生成一个新证书，然后下载安装。生成新证书时，确保是在当前 Mac 上完成“证书签名请求 (Certificate Signing Request – CSR)”的步骤，这样私钥才会自动保存在当前 Mac 的钥匙串中。
  4. 检查私钥的信任设置和访问控制：
    • 找到您的私钥，右键点击 -> 获取信息 (Get Info)。
    • 在弹出的窗口中，选择 访问控制 (Access Control) 选项卡。
    • 通常设置为： “允许所有应用程序访问此项目 (Allow all applications to access this item)” 是最省事的设置（尽管安全性略低）。或者，确保列表中包含了 /usr/bin/codesign。
    • 如果设置了“使用前询问”，那么在签名时可能会弹出密码输入框。如果这个框没有正确弹出或您输入了错误的密码，签名也会失败。为了排除故障，可以暂时设置为“允许所有应用程序访问此项目”试试。
    • 如果私钥显示为不可用或访问被拒绝，这可能是权限问题或钥匙串损坏。
  5. 评估钥匙串本身的健康状况：
    • 在钥匙串访问菜单栏中，选择 钥匙串访问 -> 证书助理 (Certificate Assistant) -> 评估证书 (Evaluate 'identity') 或 修复钥匙串 (Repair Keychain) (取决于 macOS 版本，较新的版本移除了修复选项)。
    • 如果怀疑钥匙串损坏，可以尝试在钥匙串访问中，选择 钥匙串访问 -> 偏好设置 (Preferences) -> 急救 (First Aid) (如果存在该选项) 或尝试删除并重新添加相关的证书和私钥。
    • 极端情况下，可能需要重置登录钥匙串（请谨慎操作，这会丢失所有保存在登录钥匙串中的密码！通常不建议作为首选方案）。

确保您的签名证书和与之配对的私钥都有效且在钥匙串中可访问后，再次尝试构建。如果问题依然存在，继续下一步。

步骤 4：检查 Xcode 项目的签名设置

Xcode 项目本身的构建设置必须正确指向有效的证书和描述文件。

  1. 打开项目设置：
    • 在 Xcode 项目导航器中，点击您的项目文件 (.xcodeproj)。
    • 选择您的 Target (通常是您的应用名称)。重要： 如果您的项目有多个 Target (如主应用、WatchKit Extension, iMessage Extension, Today Extension 等)，或者集成了嵌入式框架，您需要检查所有相关 Target 的签名设置。
  2. 导航到构建设置 (Build Settings)：
    • 选择 Build Settings 选项卡。
    • 搜索 Signing。
  3. 检查关键设置：
    • Code Signing Identity：
      • 检查 Debug 和 Release 配置下的设置。
      • 对于开发构建 (Debug)，通常应设置为 iOS Developer 或 Apple Development，或者自动设置为 Automatic。
      • 对于归档/发布构建 (Release)，通常应设置为 iOS Distribution 或 Apple Distribution，或者自动设置为 Automatic。
      • 如果您手动选择了特定的证书名称，请确保该证书在钥匙串中有效且有私钥。
      • 尝试将其设置为 Automatic (如果之前是手动选择)，让 Xcode 自动匹配有效的身份。
    • Provisioning Profile：
      • 检查 Debug 和 Release 配置下的设置。
      • 对于开发构建 (Debug)，应选择一个 iOS App Development 类型的描述文件，或者设置为 Automatic。
      • 对于归档/发布构建 (Release)，应选择 App Store 或 Ad Hoc 类型的描述文件，或者设置为 Automatic。
      • 如果您手动选择了特定的描述文件，请确保该描述文件在您的 Mac 上已安装且有效。
      • 尝试将其设置为 Automatic (如果之前是手动选择)，让 Xcode 自动匹配有效的描述文件。
    • Development Team：
      • 确保您选择了正确的开发团队。这个设置通常在 General 选项卡下的 Signing 部分，但也会影响 Build Settings 中的自动签名。
  4. 确保一致性：
    • 如果您的项目有多个 Target，或者项目设置和 Target 设置都存在签名项，请确保它们之间没有冲突或不一致的地方。Target 的设置会覆盖 Project 的设置。
    • 检查不同的构建配置 (Debug, Release, AdHoc 等) 是否使用了正确的签名身份和描述文件。
  5. 检查能力项 (Capabilities)：
    • 导航到 Signing & Capabilities 选项卡 (在 General 选项卡旁边)。
    • 查看您启用的能力项列表。
    • 重要： 如果您在这里添加或删除了能力项（如 Push Notifications, App Groups, Sign In with Apple 等），您必须回到 Apple Developer 网站上，编辑对应的 App ID，确保也启用了或禁用了这些能力项，然后重新生成并下载新的描述文件，并在 Xcode 中确保使用了这个新的描述文件。能力项的不匹配是导致签名失败的常见隐蔽原因。

调整项目设置后，再次尝试构建。如果问题依然存在，继续下一步。

步骤 5：检查 Bundle Identifier 与 App ID 的匹配

项目的 Bundle Identifier (通常格式是 com.yourcompany.AppName) 必须与 Provisioning Profile 所关联的 App ID 相匹配。

  1. 检查项目 Bundle Identifier：
    • 在 Xcode 中，选择您的 Target -> General 选项卡。
    • 查看 Identity 部分的 Bundle Identifier 字段。
  2. 检查描述文件关联的 App ID：
    • 回到 Apple Developer 网站 -> Certificates, Identifiers & Profiles -> Profiles。
    • 找到您使用的描述文件，查看其关联的 App ID。
    • 匹配规则：
      • 如果描述文件关联的是一个 Explicit App ID (例如 ABCDEFGHIJ.com.yourcompany.AppName)，那么您的项目的 Bundle Identifier 必须与 com.yourcompany.AppName 部分完全一致 (包括大小写)。
      • 如果描述文件关联的是一个 Wildcard App ID (例如 ABCDEFGHIJ.com.yourcompany.*)，那么您的项目的 Bundle Identifier (com.yourcompany.AppName) 必须与通配符模式匹配。
    • 常见错误： Bundle Identifier 拼写错误、大小写不匹配、末尾多了一个空格或字符等。
    • 解决： 如果不匹配，修改项目的 Bundle Identifier，使其与描述文件关联的 App ID 相符。或者，在 Apple Developer 网站上创建一个与项目 Bundle Identifier 匹配的 App ID，然后生成新的描述文件并更新 Xcode 设置。

确保 Bundle Identifier 正确匹配后，再次尝试构建。如果问题依然存在，继续下一步。

6. 处理第三方库和嵌入式框架的签名问题

如果您的项目使用了 CocoaPods, Carthage 或手动集成了嵌入式框架，这些框架可能也需要被正确签名。

  1. 检查嵌入式框架的签名设置：
    • 在 Xcode 中，选择您的 Target -> Build Phases 选项卡。
    • 找到 Embed Frameworks (或类似的名称，如 Embed Pods Frameworks)。
    • 展开该阶段，查看列表中嵌入的框架。
    • 确保每个框架的 Code Sign On Copy (复制时签名) 选项被选中（通常是默认）。这是必要的，因为嵌入式框架也需要签名才能在设备上正常加载和运行。
    • 检查第三方库的构建设置： 有些第三方库可能有自己的构建设置或脚本，可能会干扰主项目的签名过程。检查其文档或源代码是否存在相关的签名配置。
  2. CocoaPods 特定问题：
    • 有时 CocoaPods 会引入签名问题。尝试以下操作：
      • 在项目根目录下执行 pod deintegrate。
      • 删除 Podfile.lock 文件和 Pods 文件夹。
      • 执行 pod install。
    • 这会重新集成 Pods 并重新生成相关的 Xcode 项目文件和构建阶段。
  3. Carthage 特定问题：
    • 如果您手动将 Carthage 构建的框架添加到项目的 Embed Frameworks 阶段，确保 Code Sign On Copy 已勾选。

检查并修正第三方库或嵌入式框架的签名相关设置后，再次尝试构建。如果问题依然存在，继续下一步。

7. 查看详细的构建日志以获取更多信息

command codesign failed 错误本身很泛泛，但 Xcode 的构建日志通常包含更详细的错误信息，可以指向问题的根源。

  1. 打开报告导航器：
    • 在 Xcode 菜单栏中选择 View -> Navigators -> Report Navigator (或者按下快捷键 Command + 8)。
  2. 查找失败的构建任务：
    • 在报告导航器中，找到最近一次失败的构建任务（通常会标有红色感叹号）。
  3. 展开构建日志：
    • 点击该构建任务，然后在右侧区域找到并展开 Build 阶段。
    • 滚动查看输出，寻找 codesign 相关的命令行调用以及其后续的错误信息。
  4. 分析错误输出：
    • codesign 命令行的输出通常会包含更具体的错误原因，例如：
      • certificate has expired (证书已过期)
      • CSSMERR_TP_NOT_TRUSTED (证书不受信任)
      • no identity found (找不到对应的签名身份/证书)
      • specified code signing identity cannot be found (找不到指定的代码签名身份)
      • Provisioning profile "..." doesn't include signing certificate "..." (描述文件不包含指定的签名证书)
      • Provisioning profile "..." doesn't match the bundle identifier "..." (描述文件与 Bundle Identifier 不匹配)
      • Provisioning profile "..." is invalid (描述文件无效)
      • The entitlements specified in your application’s Code Signing Entitlements file are invalid, not permitted, or do not match those specified in your provisioning profile. (Entitlements 不匹配，通常是能力项问题)
    • 将这些具体的错误信息作为线索，回到前面的步骤进行更有针对性的排查。例如，如果日志明确说是证书过期，您就可以跳到步骤 2 重点检查证书；如果说是找不到身份，可能是步骤 3 的钥匙串问题或步骤 4 的项目设置问题。

仔细阅读并理解构建日志是解决 command codesign failed 错误的关键一步。它能提供比错误提示本身多得多的有用信息。

8. 清理 Derived Data

尽管步骤 1 中的 Clean Build Folder 清理了大部分构建缓存，但有时位于 Derived Data 文件夹中的其他缓存或索引文件也可能导致问题。

  1. 找到 Derived Data 路径：
    • 打开 Xcode 偏好设置：Xcode -> Preferences -> Locations -> Derived Data。点击路径旁边的箭头按钮，会在 Finder 中打开该文件夹。
    • 或者手动前往：~/Library/Developer/Xcode/DerivedData (波浪号 ~ 代表您的用户主目录)。
  2. 删除项目对应的 Derived Data 文件夹：
    • 在 DerivedData 文件夹中，找到与您项目名称相关的文件夹。
    • 关闭 Xcode。
    • 将该文件夹删除。如果您不确定是哪个文件夹，或者想彻底清理，可以删除 DerivedData 文件夹下的所有内容（这样做会删除所有项目的构建缓存，下次打开项目需要重新索引，可能耗时较长）。
  3. 重启 Xcode：
    • 删除后，重新打开 Xcode 和您的项目。

清理 Derived Data 通常能解决一些由 Xcode 内部状态或缓存引起的疑难杂症。

9. 检查系统时间和日期

系统时间和日期不正确有时会导致证书验证失败，因为证书的有效期是基于时间的。确保您的 Mac 系统时间和日期设置正确，最好设置为自动同步。

10. 检查 Apple Developer 系统状态

在极少数情况下，Apple 的开发者服务可能出现临时中断，影响证书、描述文件的验证或下载。

  • 访问 Apple 的系统状态页面：developer.apple.com/system-status/。
  • 检查与开发、证书、Provisioning Profiles 相关的服务是否处于可用状态 (绿色圆点)。

11. 重置或修复权限

在 macOS 中，权限问题有时会导致 codesign 工具无法访问签名所需的资源。

  • 修复磁盘权限 (较旧 macOS 版本)： 在较旧的 macOS 版本中，可以通过磁盘工具修复权限。在较新的版本中，系统文件权限受 System Integrity Protection (SIP) 保护，一般不需要手动修复。
  • 重置隐私设置 (macOS Mojave 及以上)： 如果 codesign 工具被阻止访问某些文件或资源（尽管不常见），可以在 系统设置/系统偏好设置 -> 隐私与安全性/安全性与隐私 -> 隐私 -> 开发者工具 中，确保 Xcode 具有完整的磁盘访问权限（如果需要）。

12. 检查 Xcode 版本兼容性

确保您使用的 Xcode 版本支持当前 macOS 版本、您的项目类型以及您尝试构建的目标操作系统版本。虽然版本不兼容通常会导致其他构建错误，但有时也可能间接影响签名过程。

13. 导出和导入开发者账户信息

有时，Xcode 与 Apple Developer 账户的连接状态可能出现问题。

  1. 从 Xcode 移除账户： 在 Xcode -> Preferences -> Accounts 中，选择您的 Apple ID，点击 - 按钮移除。
  2. 重新添加账户： 点击 + 按钮，重新添加您的 Apple ID。Xcode 会尝试从 Apple 下载您的证书和描述文件。
  3. 下载手动描述文件： 添加账户后，选中您的 Apple ID，点击 Manage Certificates... 检查证书，并点击 Download Manual Profiles 确保所有描述文件都已下载。

14. 检查 .entitlements 文件

能力项 (Capabilities) 对应着应用的 Entitlements。当您在项目中启用能力项时，Xcode 会生成或修改一个 .entitlements 文件（通常以 .entitlements 结尾，可能位于项目根目录或特定 Target 文件夹下）。确保这个文件存在，格式正确（XML），并且其中列出的权限与您的 App ID 和 Provisioning Profile 中启用的能力项一致。手动编辑 .entitlements 文件时需要格外小心。通常推荐通过 Xcode 的 Signing & Capabilities 界面管理能力项，让 Xcode 自动处理这个文件。

15. 极端情况：重新安装 Xcode

如果以上所有步骤都未能解决问题，并且您怀疑 Xcode 安装本身有问题，最后的手段是彻底卸载并重新安装 Xcode。

  • 将 /Applications/Xcode.app 移动到废纸篓并清空。
  • 删除相关的开发者支持文件：~/Library/Developer/ (请谨慎，备份重要数据)。
  • 从 Mac App Store 或 Apple Developer 网站下载最新版本的 Xcode 进行安装。

重要提示： 重新安装 Xcode 是一个耗时且可能影响其他项目的操作，请作为最后的解决方案。

预防未来出现签名问题

  • 定期检查证书和描述文件： 在它们过期前就进行更新。可以在日历中设置提醒。
  • 理解证书和私钥的管理： 知道哪些证书需要有私钥，并在更换电脑或团队成员时正确导出和导入 .p12 文件。
  • 标准化签名流程： 如果是团队开发，确保所有成员遵循一致的证书和描述文件管理流程。考虑使用自动化工具或脚本来检查签名状态。
  • 谨慎更改 Bundle Identifier 和能力项： 任何更改都需要同步更新 App ID 和 Provisioning Profile。
  • 使用 Automatic Signing (自动管理签名)： 在大多数情况下，让 Xcode 自动管理签名可以减少手动配置错误，只要您的 Apple Developer 账户和钥匙串状态是健康的。但也要了解在自动签名失败时，如何切换到手动签名进行诊断。

总结

command codesign failed with a nonzero exit code 是一个棘手的错误，但通过系统性地检查证书、描述文件、钥匙串访问、项目设置、Bundle Identifier、能力项以及构建日志，几乎总是能够找到问题的根源并解决它。

解决这个错误的关键在于：

  1. 理解 代码签名的原理和组成部分（证书、私钥、App ID、描述文件）。
  2. 耐心 按照步骤逐一排查，不跳过任何可能的环节。
  3. 善于利用 构建日志获取更详细的错误信息。

希望这篇详细的指南能够帮助您有效地诊断并彻底解决 Xcode 中的代码签名失败问题。祝您开发顺利！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部