详解 command codesign failed with a nonzero exit code 错误及处理方法 – wiki基地

作者： /

详解 macOS/Xcode 开发中的棘手问题：command codesign failed with a nonzero exit code 错误及处理方法

在 macOS 或 iOS 应用开发中，开发者常常会遇到一个令人沮丧的错误：command codesign failed with a nonzero exit code。这个错误信息本身非常通用，仅仅表明 macOS 的代码签名工具 codesign 在尝试对你的应用或框架进行签名时遇到了问题，并且没有成功完成任务（非零退出码通常表示错误）。它不会直接告诉你 为什么 签名失败，这使得问题的诊断变得复杂。

本文将深入探讨这个错误的原因、它在开发流程中的意义，以及一套系统性的诊断和解决该问题的方法，旨在帮助开发者快速定位并修复这个常见的签名错误。

1. 什么是代码签名（Code Signing）？为什么它如此重要？

在深入探讨错误之前，理解代码签名的概念至关重要。

代码签名是一种安全技术，用于验证软件的来源和完整性。在 macOS 和 iOS 生态系统中，Apple 强制要求几乎所有分发和运行的应用程序都必须进行代码签名。其主要目的包括：

  1. 身份验证 (Authentication): 证明软件是由一个已知的、受信任的开发者（通过其开发者证书标识）发布的。
  2. 完整性验证 (Integrity): 确保软件自发布以来没有被篡改或损坏。
  3. 授权和能力 (Authorization & Capabilities): 签名过程会将应用程序的某些特殊权限（如 Push Notifications、App Groups、Keychain Sharing 等）与特定的开发者身份和 Provisioning Profile 相关联，允许应用在沙盒环境中获得这些能力。
  4. 分发和安装 (Distribution & Installation): Apple 的 App Store、TestFlight 以及在设备上运行应用的机制都依赖于有效的代码签名来允许应用的安装和启动。例如，iOS 设备只允许运行经过有效签名并与设备 UDID 关联的应用（通过 Provisioning Profile 实现）。

codesign 是 macOS 提供的一个命令行工具，用于执行代码签名操作。Xcode 在构建应用时，会在幕后调用 codesign 工具来完成应用的签名。当 codesign 执行失败时，Xcode 就会报告 command codesign failed with a nonzero exit code 错误。

2. command codesign failed with a nonzero exit code 错误是如何发生的？

这个错误本质上是 codesign 工具执行失败后返回的一个通用错误码。它可能发生在 Xcode 构建过程的签名阶段。在 Xcode 构建一个应用时，通常会经历编译、链接、拷贝资源等多个步骤，最后一步或者其中关键的一步就是使用 codesign 工具对生成的可执行文件、捆绑包（Bundle）以及其中包含的框架、插件等进行签名。

当 codesign 工具在执行过程中遇到任何问题（例如找不到签名所需的私钥、证书过期、Profile 不匹配、文件损坏等），它就会停止执行并返回一个非零的退出码，告诉 Xcode “我失败了”。Xcode 捕获到这个非零退出码后，就会在构建日志中显示 command codesign failed with a nonzero exit code 错误，并停止构建过程。

关键点: 这个错误信息本身没有提供具体的失败原因。真正的错误信息通常隐藏在 构建日志 (Build Log) 的前面部分。因此，诊断这个错误的首要步骤是查看详细的构建日志。

3. 常见导致 command codesign failed with a nonzero exit code 错误的原因

这个错误可以由多种原因引起，其中最常见的原因围绕着代码签名所需的“三要素”：证书 (Certificate)、私钥 (Private Key) 和 Provisioning Profile，以及它们与你的项目设置、系统环境和依赖项的匹配关系。

以下是导致该错误的常见原因列表：

3.1 证书（Certificates）问题

  1. 缺少证书: 你尝试签名的开发者身份对应的证书没有安装在你的 Mac 上。
  2. 证书过期: 用于签名的开发者证书已经过期。
  3. 证书已被吊销 (Revoked): 证书在 Apple Developer Portal 中被吊销。
  4. 缺少私钥: 证书安装在你的 Mac 上，但与之配对的私钥丢失了。没有私钥，codesign 无法使用该证书进行签名。证书和私钥必须配对存在于你的 Keychain 中。
  5. 证书不受信任: 证书链不完整或根证书不受信任。
  6. Keychain 访问问题: codesign 工具没有权限访问存储在 Keychain Access 中的证书和私钥。

3.2 Provisioning Profile 问题

  1. 缺少 Provisioning Profile: 项目设置中指定的 Provisioning Profile 没有下载并安装在你的 Mac 上。
  2. Provisioning Profile 过期: Provisioning Profile 已经过期。
  3. Provisioning Profile 无效: Profile 在 Apple Developer Portal 中已被标记为无效（例如，关联的证书过期或吊销，或者关联的 App ID 被删除）。
  4. Provisioning Profile 与 App ID 不匹配: Profile 绑定的 App ID (com.yourcompany.yourappname) 与你项目设置中的 Bundle Identifier (Bundle ID) 不一致。
  5. Provisioning Profile 类型不匹配: 尝试使用开发 (Development) Profile 进行发布 (Distribution) 构建，或反之。或者 Profile 不支持当前构建类型（例如，Ad Hoc Profile 用于 App Store 构建）。
  6. Provisioning Profile 与设备不匹配 (仅限 Development/Ad Hoc): 尝试在 Profile 中未包含的设备上运行应用。
  7. Capabilities 不匹配: Provisioning Profile 中启用的 Capabilities（如 Push Notifications, App Groups, Wallet 等）与项目设置中启用的 Capabilities 不一致。

3.3 项目构建设置（Build Settings）问题

  1. Code Signing Identity 设置错误: 项目或目标 (Target) 的 Code Signing Identity 设置指向了一个不存在、过期或不匹配的开发者身份。
  2. Provisioning Profile 设置错误: 项目或目标的 Provisioning Profile 设置指向了一个不存在、过期或不匹配的 Profile。
  3. Automatic Signing 问题: 当使用 Xcode 的“Automatically manage signing”功能时，如果 Apple Developer 账号信息、证书、Profile 或设备出现问题，Xcode 可能无法自动生成或更新所需的签名资产，导致签名失败。
  4. Inherited Settings 问题: 项目、Target 或 Pods/Frameworks 的签名设置通过继承方式传递，但某个层级的设置不正确。

3.4 项目配置（Project Configuration）问题

  1. Bundle Identifier 问题: 项目的 Bundle Identifier 与 Provisioning Profile 中的 App ID 不匹配。这通常与 Provisioning Profile 问题同时出现。
  2. Capabilities/Entitlements 问题: 项目中启用了某些 Capabilities，但在 Apple Developer Portal 中对应的 App ID 或 Provisioning Profile 中没有启用，或者 Entitlements 文件配置错误。

3.5 依赖项（Dependencies）或嵌入式框架（Embedded Frameworks）问题

  1. 未签名或签名不正确: 项目依赖的第三方库、Frameworks (通过 CocoaPods, Carthage, Swift Package Manager 或手动添加) 没有正确签名，或者使用了与主应用不兼容的签名身份。
  2. 损坏的 Frameworks: 嵌入的 Frameworks 文件损坏。

3.6 Keychain Access 问题

  1. Keychain 未解锁: 存储私钥的 Keychain（通常是 ‘login’）在构建时被锁定。
  2. ** Keychain 中存在冲突或冗余项:** Keychain 中存在多个同名的证书/私钥对，或者存在损坏的 Keychain 条目。
  3. Keychain 权限问题: codesign 工具或 Xcode 没有被授予访问私钥的权限。

3.7 Xcode 或 macOS 环境问题

  1. Xcode Bug 或 Glitch: Xcode 本身可能出现临时性的问题。
  2. Derived Data 缓存问题: Xcode 的缓存数据可能损坏。
  3. 系统时间错误: Mac 的系统时间不准确可能影响证书和 Profile 的有效期判断。
  4. 网络问题: 在使用自动签名或需要从 Apple Developer Portal 下载资产时，网络不稳定可能导致失败。

4. 诊断和解决 command codesign failed with a nonzero exit code 的系统方法

面对这个错误，采取系统性的方法进行诊断和解决是最高效的。以下是一个推荐的排查流程：

步骤 1: 查看详细的构建日志 (Build Log) – 最重要的一步！

不要只看错误提示 command codesign failed with a nonzero exit code。在 Xcode 的 Report Navigator (视图 -> 导航器 -> 显示报告导航器，或者使用快捷键 ⌘8) 中找到失败的构建任务。展开构建步骤，查找 CodeSign 步骤，并查看其输出详情。

通常，真正的错误原因会在 command codesign failed... 这行之前输出。仔细阅读这些详细的错误信息，它们可能会明确指出是证书无效、Profile 不匹配、文件不存在等具体问题。例如，你可能会看到：

  • CSSMERR_TP_CERT_EXPIRED (证书过期)
  • certificate revoked (证书被吊销)
  • no identity found (找不到匹配的签名身份/私钥)
  • Provisioning Profile "..." doesn't include signing certificate "..." (Profile 不包含指定的签名证书)
  • A valid provisioning profile matching the application's bundle identifier '...' could not be found. (找不到与 Bundle ID 匹配的有效 Profile)
  • ... is not a valid ad hoc profile. (不是有效的 Ad Hoc Profile)
  • The entitlements specified in your application’s Code Signing Entitlements file do not match the ones specified in your provisioning profile. (Entitlements 与 Profile 不匹配)
  • ... has conflicting provisioning settings (存在冲突的 Profile 设置)

这些详细信息将大大缩小问题的范围。根据日志中的具体错误，你可以直接跳到相应的解决方案。

步骤 2: 执行基本的清洁和重启

如果日志信息不够明确，或者尝试某个解决方案后问题依旧，先执行以下基本操作：

  1. Clean Build Folder: 在 Xcode 中选择 Product -> Clean Build Folder (快捷键 ⇧⌘K)。这会删除旧的构建文件和中间产物，有时可以解决由旧缓存引起的问题。
  2. Delete Derived Data: 关闭 Xcode。手动删除项目的 Derived Data 文件夹。该文件夹通常位于 ~/Library/Developer/Xcode/DerivedData/。这是 Xcode 存储索引、模块缓存和构建输出的地方。删除它可以强制 Xcode 重新生成这些文件。
  3. Restart Xcode: 关闭并重新打开 Xcode。
  4. Restart Your Mac: 有时，简单的系统重启可以解决临时的 Keychain 或系统资源问题。

步骤 3: 检查证书和私钥

  1. 打开 Keychain Access: 启动 Spotlight ( ⌘Space) 搜索 “Keychain Access” 并打开它。
  2. 检查 “login” Keychain: 在左侧导航栏选择 “login” Keychain。
  3. 检查 “My Certificates”: 在左下角选择 “My Certificates”。查找你在 Xcode 项目设置中使用的开发者身份（例如 “Apple Development: Your Name (Team ID)” 或 “Apple Distribution: Your Name (Team ID)”）。
  4. 验证证书有效性:
    • 查看证书的有效期，确保它没有过期。
    • 双击证书查看详情。确保其状态是 “This certificate is valid”。
    • 最关键的是: 确保证书旁边有一个小的展开箭头 (▶)。展开它，下面应该显示一个与证书名称匹配的私钥 (Private Key)。缺少私钥是签名失败的常见原因。
  5. 检查 “Certificates” 和 “Keys”: 切换到左下角的 “Certificates” 和 “Keys” 分类，查找相关的证书和私钥，确保它们存在且有效。
  6. 修复或重新创建/下载证书:
    • 如果证书过期、吊销或缺失，登录 Apple Developer Portal。
    • 导航到 Certificates, Identifiers & Profiles -> Certificates。
    • 查找你需要证书。如果已过期或吊销，考虑吊销旧的并创建新的（注意：吊销证书可能会影响依赖该证书的其他应用）。
    • 下载新的证书文件 (.cer)。双击下载的文件，它会自动安装到 Keychain Access。
    • 如果缺少私钥: 你需要找到最初创建该证书时生成的私钥文件（通常在你创建证书的 Mac 上），或者如果找不到，则需要吊销现有证书并在当前 Mac 上重新创建一个新的开发者身份（这将生成一个新的证书和私钥对）。请注意备份你的私钥文件（通常以 .p12 格式导出）。
  7. 检查 Keychain 访问权限:
    • 双击 Keychain Access 中的私钥。
    • 选择 “Access Control” 选项卡。
    • 确保 Xcode 或 codesign 工具有权访问此私钥。通常，“Allow all applications to access this item” 是最简单的设置，但在更安全的配置中，你需要明确添加 /usr/bin/codesign 和你的 Xcode 应用。如果之前有弹窗询问权限你拒绝了，这里可能需要调整。

步骤 4: 检查 Provisioning Profile

  1. 检查 Xcode 中的 Profiles:
    • 打开 Xcode 设置 (Xcode -> Settings 或 Preferences)。
    • 转到 Accounts 选项卡。
    • 选择你的 Apple ID 账号。
    • 选择你的开发团队。
    • 点击 “Download Manual Profiles” 或 “Manage Certificates…” -> “Download Manual Profiles”。确保你需要的 Profile 已经下载。你也可以在这里看到已安装的 Profile 列表和它们的有效期。
  2. 检查 Apple Developer Portal 中的 Profiles:
    • 登录 Apple Developer Portal。
    • 导航到 Certificates, Identifiers & Profiles -> Profiles。
    • 查找你在项目设置中使用的 Provisioning Profile。
    • 验证 Profile 有效性:
      • 检查 Profile 的状态（Status），确保它是 “Active” 或 “Valid”，而不是 “Invalid” 或 “Expired”。
      • 检查 Profile 的有效期，确保它没有过期。
      • 查看 Profile 关联的 App ID，确保它与你的项目 Bundle Identifier 完全匹配。
      • （如果是 Development 或 Ad Hoc Profile）检查关联的设备列表是否包含你要测试的设备。
      • 检查关联的证书是否是你当前系统中有效且带有私钥的证书。
      • 检查 Profile 中启用的 Capabilities 是否与项目设置一致。
  3. 修复或重新生成 Profile:
    • 如果 Profile 过期、无效或配置不正确，在 Developer Portal 中编辑或删除它，然后重新生成一个新的 Profile。
    • 下载新的 Profile 文件 (.mobileprovision)。双击下载的文件，它会自动安装。有时需要将文件拖动到 Xcode 的 Dock 图标上强制安装。
  4. 删除旧的或冲突的 Profiles: 在 ~/Library/MobileDevice/Provisioning Profiles/ 文件夹中，手动删除与项目相关的旧的、无效的或冲突的 .mobileprovision 文件，然后重新安装所需的 Profile。这有助于清除可能导致混淆的旧数据。

步骤 5: 检查 Xcode 项目构建设置 (Build Settings)

确保项目和目标 (Target) 的签名设置是正确的。

  1. 打开项目设置: 在 Xcode Project Navigator 中选择你的项目，然后选择你的 Target。
  2. 转到 “Signing & Capabilities” 选项卡:
    • 如果使用 “Automatically manage signing”: 确保勾选了此选项。选择正确的 Team。检查下方是否有任何警告或错误信息（如“Failed to create provisioning profile.”）。尝试取消勾选再重新勾选此选项，让 Xcode 重新尝试管理签名。确保你的 Apple ID 账号已在 Xcode 中正确添加并登录。
    • 如果手动管理签名: 取消勾选 “Automatically manage signing”。
      • Code Signing Identity: 确保为 Debug 和 Release 构建配置选择了正确的开发者身份（例如，“Apple Development”或“Apple Distribution”）。下拉菜单中应该只显示当前系统中有私钥的有效证书。如果下拉菜单中没有显示你期望的身份，回到步骤 3 检查证书和私钥。
      • Provisioning Profile: 确保为 Debug 和 Release 配置选择了正确的 Provisioning Profile。下拉菜单中应该列出已安装的 Profile。选择与你的 Bundle ID、构建类型和签名身份匹配的 Profile。如果列表为空或没有你需要的 Profile，回到步骤 4 检查并安装 Profile。
  3. 检查 Build Settings 选项卡:
    • 搜索 “Code Signing Identity” 和 “Provisioning Profile”。确认在所有相关的构建配置（如 Debug, Release）和适用的层级（Project 和 Target）都设置了正确的值。注意层级继承关系。如果 Target 设置了，它会覆盖 Project 的设置。
    • 检查 PROVISIONING_PROFILE_SPECIFIER 或 PROVISIONING_PROFILE 的值。
    • 确保 DEVELOPMENT_TEAM 设置正确。

步骤 6: 检查 Bundle Identifier 和 Capabilities/Entitlements

  1. 检查 Bundle Identifier: 在 Project Navigator 中选择你的 Target，转到 “General” 选项卡，确认 “Bundle Identifier” (com.yourcompany.yourappname) 与你的 Provisioning Profile 中对应的 App ID 完全一致。
  2. 检查 Capabilities: 在 Target 的 “Signing & Capabilities” 选项卡中，检查所有启用的 Capabilities（如 Push Notifications, App Groups, Associated Domains 等）。
    • 登录 Apple Developer Portal，导航到 Certificates, Identifiers & Profiles -> Identifiers。
    • 找到与你的 Bundle Identifier 对应的 App ID。
    • 编辑该 App ID，确保其中启用的 Services (Capabilities) 与你在 Xcode 项目中启用的完全一致。
    • 重新生成并下载关联了更新后 App ID 的 Provisioning Profile。
  3. 检查 Entitlements 文件: 如果你的项目使用了自定义的 .entitlements 文件，确保文件内容正确，并且与你的 Provisioning Profile 允许的权限一致。通常，Xcode 会根据你在 “Signing & Capabilities” 选项卡中勾选的功能自动生成或更新这个文件。

步骤 7: 检查依赖项和嵌入式框架

如果你的项目使用了 CocoaPods、Carthage 或 Swift Package Manager 引入了第三方 Frameworks，或者手动添加了嵌入式 Frameworks，这些 Frameworks 也需要正确签名。

  1. 检查 Frameworks 的签名:
    • 构建失败后，在 Finder 中找到你应用的 .app 文件（通常在 Derived Data 或构建输出目录）。右键点击 .app -> “Show Package Contents”。导航到 Contents/Frameworks/ 目录。
    • 打开 Terminal，使用 codesign -dvvvv /path/to/your.framework 命令检查每个嵌入式 Framework 的签名信息。查看其签名状态、身份等。
  2. 解决 Framework 签名问题:
    • 对于 CocoaPods: Pods 项目通常会由 CocoaPods 自动处理签名。确保你的 Podfile 配置正确，并在运行 pod install 后，检查生成的 Pods.xcodeproj 中的签名设置是否与你的主项目兼容。有时，更新 CocoaPods 或清理 Pods 缓存 (pod cache clean --all) 并重新安装 (pod install) 可以解决问题。
    • 对于 Carthage: Carthage 默认不签名构建的 Frameworks。你需要在构建脚本中添加签名步骤。常见的做法是在 Xcode 的 Build Phases 中添加一个 Run Script Phase，用于遍历 Carthage 构建的 Frameworks 目录并使用 codesign 命令进行签名。确保签名命令使用了正确的签名身份和 Entitlements。
    • 对于 Swift Package Manager: Xcode 通常会处理 Swift Package 依赖的签名。确保依赖包本身没有签名问题。
    • 对于手动添加的 Frameworks: 确保你添加的 Frameworks 是有效的，并且在构建过程中它们能够被正确签名（例如，通过在 Build Phases 中设置 “Embed & Sign”）。如果 Framework 是你自己构建的，确保你在构建 Framework 时使用了正确的签名。
    • 如果某个 Framework 是由其提供者签名的，确保你信任该签名。有时你需要获取未签名的版本，并在你的项目中自行签名。

步骤 8: 高级故障排除

如果以上步骤都无法解决问题，考虑以下更高级的排查方法：

  1. 查看更详细的 codesign 输出: 在 Xcode 的 Build Settings 中搜索 “Other Code Signing Flags”，尝试添加 -v -v -v -v（verbose 模式）到你的签名 Flag 中。这将使得 codesign 命令输出更多诊断信息到构建日志中。
  2. 手动运行 codesign 命令: 尝试从 Terminal 中手动运行 Xcode 在构建日志中显示的 codesign 命令（复制粘贴出来），看看在命令行中它输出的具体错误是什么。这可以隔离问题是否仅发生在 Xcode 环境中。你需要找到 Xcode 构建输出的未签名应用路径。
  3. 检查文件权限或损坏: 确保 Xcode 对项目文件和构建输出目录有读写权限。虽然不常见，但文件系统权限问题或文件本身损坏（尤其是 Frameworks 或资源文件）也可能导致签名失败。尝试清理项目目录并重新获取代码。
  4. 检查系统时间: 确保你的 Mac 的系统时间设置正确且与网络时间同步。不正确的系统时间会影响证书和 Profile 的有效期判断。
  5. 网络环境: 确保在构建过程中你的网络连接稳定，特别是在使用自动签名或需要从 Apple Developer Portal 同步信息时。防火墙或网络代理设置也可能干扰与 Apple 服务器的通信。

5. 预防 codesign failed 错误的最佳实践

  • 定期检查证书和 Profile 有效期: 在 Apple Developer Portal 和 Xcode 设置中设置提醒或定期检查。
  • 理解签名设置: 无论是使用自动签名还是手动管理，都要理解 Xcode 中签名设置的含义以及它们与 Apple Developer Portal 中资产的关系。
  • 小心处理 Keychain: 避免在 Keychain Access 中随意删除证书或私钥，除非你确定它们的用途并有备份。定期备份你的开发者身份 (.p12 文件)。
  • 系统化管理 Provisioning Profiles: 保持你的 Profile 列表整洁，及时删除过期或不需要的 Profile。
  • 版本控制项目文件: 将 .xcodeproj 或 .xcworkspace 文件纳入版本控制，以便在签名设置被意外更改时能够回滚。
  • 理解依赖项的签名要求: 如果引入第三方 Frameworks，了解它们是否需要签名，以及如何在你的构建过程中正确处理它们的签名。
  • 保持 Xcode 和 macOS 更新: 及时更新到最新版本的 Xcode 和 macOS，这可以修复已知的 Bug 并改进签名流程。

6. 总结

command codesign failed with a nonzero exit code 是一个通用的错误信息，意味着 codesign 工具在执行过程中遇到了问题。解决这个错误的关键在于：

  1. 永远先查看详细的构建日志，它通常包含更具体的错误原因。
  2. 系统性地排查证书、私钥、Provisioning Profile、项目设置、依赖项以及 Keychain Access 等可能的问题点。
  3. 理解代码签名背后的原理，能够帮助你更好地定位和解决问题。

通过遵循本文提供的诊断步骤和解决方法，你应该能够有效地解决大部分 command codesign failed with a nonzero exit code 错误，确保你的应用能够被正确签名、构建和分发。耐心和细致是解决这类问题的关键。

发表评论

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

滚动至顶部