Xcode 错误 command codesign failed 解决方案 – wiki基地

作者： /

解决 Xcode 中的“command codesign failed”错误：一份详细指南

在 iOS 和 macOS 开发过程中，command codesign failed 是一个开发者经常会遇到的令人沮丧的错误。它意味着 Xcode 在尝试对您的应用或 bundle 进行签名时遇到了问题。代码签名是 Apple 平台上的一个核心安全机制，用于验证应用的开发者身份、确保应用在发布后未被篡改，并控制应用对特定系统资源的访问（通过 Entitlements 和 Provisioning Profile）。因此，当签名过程失败时，您的构建就会停止，无法在真机设备上运行、发布到 App Store 或进行企业分发。

本文将深入探讨 command codesign failed 错误的原因，并提供一套系统性的、详细的故障排除步骤，帮助您快速定位并解决问题。

1. 理解代码签名的重要性与组成部分

在解决问题之前，了解代码签名是什么以及为什么它会失败至关重要。Apple 的代码签名机制主要包含以下几个关键组成部分：

  • 证书 (Certificates): 由 Apple 颁发，用于验证您的开发者身份。常见的有 Apple Development（开发证书）和 Apple Distribution（分发证书）。证书与一对公钥和私钥相关联。
  • 私钥 (Private Key): 存储在您的 Mac 上的“钥匙串访问” (Keychain Access) 应用中。它是与公钥配对的，用于对您的应用进行实际签名。只有拥有与证书匹配的私钥，您才能使用该证书进行签名。
  • Provisioning Profile (描述文件): 由 Apple Developer Portal 生成，包含了您的证书、App ID（应用的唯一标识符）以及（对于开发和 Ad Hoc 分发）允许运行应用的设备列表。它授权特定应用在特定设备上运行或以特定方式发布（App Store, Enterprise）。Provisioning Profile 也包含了允许应用使用特定功能（Capabilities，如 Push Notifications, App Groups, iCloud 等）的 Entitlements 信息。
  • App ID: 在 Apple Developer Portal 中注册，用于唯一标识您的应用。可以是 Explicit App ID（如 com.yourcompany.yourapp）或 Wildcard App ID（如 com.yourcompany.*）。
  • Team ID: 您的 Apple Developer 账号的唯一标识符，通常是一个10位字母数字字符串。
  • Entitlements: 授予应用访问特定系统资源或服务的权限（如 Push Notifications, Keychain Sharing, App Groups, Sign In with Apple 等）。这些权限在 Xcode 中配置，并嵌入到 Provisioning Profile 中。

codesign 命令是 macOS 系统的一个工具，Xcode 在构建过程的最后阶段会调用它来使用指定的证书和 Provisioning Profile 对您的应用 Bundle 进行签名。如果 codesign 命令无法找到所需的签名身份、无法访问私钥、Provisioning Profile 无效、或Provisioning Profile与应用设置不匹配，就会抛出 command codesign failed 错误。

2. 常见的“command codesign failed”错误原因

command codesign failed 错误可能由多种因素引起，常见的包括：

  1. 证书/私钥问题:
    • 证书已过期。
    • 证书已被吊销 (Revoked)。
    • 在“钥匙串访问”中找不到与证书匹配的私钥。
    • 私钥的访问权限有问题（codesign 命令无法访问）。
    • 存在多个相同的证书或私钥，导致混淆。
    • 从其他 Mac 导入的证书没有包含私钥。
  2. Provisioning Profile 问题:
    • Provisioning Profile 已过期。
    • Provisioning Profile 已被吊销。
    • Provisioning Profile 中不包含用于签名的有效证书。
    • Provisioning Profile 中不包含当前用于构建的设备（仅适用于 Development 和 Ad Hoc）。
    • Provisioning Profile 的 App ID 与您的项目 Bundle Identifier 不匹配。
    • Provisioning Profile 不支持项目启用的特定 Capabilities (Entitlements)。
    • 在 Xcode 中选择了错误的 Provisioning Profile。
  3. Xcode 项目配置问题:
    • Build Settings 中“Code Signing Identity”或“Provisioning Profile”设置不正确或存在冲突。
    • Automatic Signing 设置问题。
    • Manual Signing 设置与实际证书/Profile 不匹配。
    • Bundle Identifier 与 Provisioning Profile 中的 App ID 不匹配。
    • 项目启用的 Capabilities 与 Provisioning Profile 中的 Entitlements 不匹配。
    • 引用了未签名的第三方库或 Embedded Frameworks。
  4. 环境/系统问题:
    • Keychain Access 访问权限问题。
    • Xcode 或 macOS 版本过旧，与项目或签名资产不兼容。
    • 网络问题（无法连接到 Apple 服务器验证证书/Profile）。
    • Xcode 缓存或构建目录损坏。
    • 项目文件本身损坏。
  5. 多账号/多团队问题:
    • 同一台 Mac 上登录了多个 Apple ID，导致钥匙串中的证书混淆。
    • 项目设置使用了错误的 Team ID。

了解这些潜在原因，有助于我们更有针对性地进行故障排除。

3. 系统性的故障排除步骤

解决 command codesign failed 错误需要采取系统性的方法，从最常见、最简单的检查开始，逐步深入。

步骤 1: 基本检查与快速修复

在进行任何复杂操作之前，先尝试一些简单的步骤，它们经常能解决临时的构建问题。

  1. 重启 Xcode: 关闭 Xcode 后重新打开，有时能清除内部状态或缓存问题。
  2. 清理构建目录: 在 Xcode 菜单栏选择 Product > Clean Build Folder (快捷键 Shift + Command + K)。这会删除所有构建生成的文件，迫使 Xcode 从头开始构建，有时能解决由旧的或损坏的构建文件引起的问题。
  3. 重启 Mac: 如果重启 Xcode 无效，尝试重启您的电脑。这可以刷新系统状态、解决潜在的进程冲突或系统级缓存问题。
  4. 检查 Bundle Identifier: 确保您的项目设置 (General tab 或 Build Settings 的 PRODUCT_BUNDLE_IDENTIFIER) 中的 Bundle Identifier (com.yourcompany.yourapp) 与您期望使用的 Provisioning Profile 中的 App ID 完全匹配。注意大小写和任何拼写错误。

如果这些简单步骤未能解决问题，请继续进行更深入的检查。

步骤 2: 检查 Xcode 的签名设置

Xcode 的签名设置是出现问题最频繁的地方。

  1. 打开项目设置: 在 Project Navigator 中选择您的项目，然后选择您的 Target。
  2. 进入 Signing & Capabilities 选项卡: 这是 Xcode 11 及更高版本管理签名的地方。
  3. 检查 Team: 确保选择了正确的 Team。如果您属于多个开发团队，这里可能会出错。
  4. 检查 Bundle Identifier: 再次确认这里的 Bundle Identifier 是正确的。

  5. Automatic Signing vs. Manual Signing:

    • 使用 Automatic Signing: 如果勾选了“Automatically manage signing”，Xcode 会尝试根据您的 Team、Bundle Identifier 和所需的 Capabilities 自动为您创建和更新 Provisioning Profile。确保您的 Xcode 账户中已添加并登录了正确的 Apple ID (Xcode > Settings (or Preferences) > Accounts)。如果 Xcode 报告找不到签名身份或 Provisioning Profile，通常是因为钥匙串中缺少必要的证书/私钥或 Apple Developer Portal 中缺少相应的 Profile。
    • 使用 Manual Signing: 如果取消勾选“Automatically manage signing”，您需要手动在 Build Settings 中指定 Code Signing Identity 和 Provisioning Profile。确保您在“Signing & Capabilities”中选择了正确的 Team，并且下面的 Provisioning Profile 和 Signing Certificate 选项中选择了有效的、您期望使用的资产。

  6. 检查 Build Settings 中的详细签名设置: 即使使用 Automatic Signing，理解并检查 Build Settings 也是有益的，因为它们有时会覆盖自动设置。

    • 选择您的项目或 Target，进入 Build Settings 选项卡。
    • 将筛选条件设置为 All 和 Combined。
    • 搜索 Signing。

    • 检查以下设置：

      • Code Signing Identity: 确保 Debug、Release 或其他相关配置都指向了正确的签名身份（例如 “Apple Development”, “Apple Distribution”, 或具体的证书名称）。选择 iOS Developer 或 iOS Distribution 等通用选项通常依赖于钥匙串中是否有匹配的有效证书。如果指定了具体的证书名称（如 “Apple Distribution: Your Name (TEAMID)”），请确保该证书在钥匙串中存在且有效。
      • Provisioning Profile: 确保 Debug、Release 或其他相关配置都指向了正确的 Provisioning Profile。这可以是 Profile 的 UUID，也可以是 Profile 的名称。确保选择了与 Code Signing Identity 和 Bundle Identifier 匹配的 Profile。
      • Development Team: 确保这里设置了正确的 Team ID。
      • CODE_SIGN_STYLE: 确认是 Automatic 还是 Manual，并与您在 Signing & Capabilities 中的选择一致。

    • 特别注意 Resolved Build Settings: 在 Build Settings 选项卡底部有一个 Resolved 选项。选择您的构建配置（Debug 或 Release）和 SDK，查看 Xcode 最终解析出的签名设置。这可以帮助您找出潜在的覆盖问题。

步骤 3: 检查 Apple Developer Account 和 Portal

签名资产的有效性由 Apple Developer Portal 控制。

  1. 登录 Apple Developer Account: 访问 https://developer.apple.com/account/ 并登录。
  2. 检查 Member Center 状态: 确保您的开发者账号处于活动状态，没有过期或有待处理的协议更新。
  3. 检查 Certificates (证书):
    • 导航到 Certificates, Identifiers & Profiles > Certificates。
    • 查找您用于开发的 Apple Development 证书和用于分发的 Apple Distribution 证书。
    • 检查它们的状态（Status）：是否是 Active？是否已 Expired？是否被 Revoked？
    • 检查有效期 (Expiration Date)。如果过期，需要创建新的证书。
    • 如果您使用的是旧版的 iOS Development/Distribution 证书，检查它们是否仍然有效。
    • 如果缺少必要的证书，点击右上角的 + 创建。创建时通常需要上传一个 Certificate Signing Request (CSR) 文件，该文件在 Mac 的“钥匙串访问”中生成 (Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority...)。
  4. 检查 Provisioning Profiles (描述文件):
    • 导航到 Certificates, Identifiers & Profiles > Profiles。
    • 查找您用于构建的 Provisioning Profile（例如，iOS App Development, App Store, Ad Hoc, In House）。
    • 检查它们的状态（Status）：是否是 Active？是否是 Invalid？是否是 Expired？
    • 如果状态是 Invalid，通常是因为相关的证书已过期或被吊销，或者 Profile 中的设备列表已更改。编辑 Profile，重新选择有效的证书，更新设备列表，然后生成并下载新的 Profile。
    • 检查 Provisioning Profile 的信息：
      • Profile Type（类型是否正确？Development, App Store, Ad Hoc, Enterprise？）
      • App ID（是否与您的项目 Bundle Identifier 匹配？）
      • Certificates（是否包含了您希望用于签名的有效证书？）
      • Devices（对于 Development 和 Ad Hoc Profile，是否包含了您要安装应用的设备？）。
      • Expiration Date（是否已过期？）
    • 如果 Profile 无效或过期，或者需要更新设备列表/证书，编辑并重新生成 Profile。生成后，下载新的 Profile 文件 (.mobileprovision)。
    • 将新的/更新的 Provisioning Profile 添加到 Xcode: 有几种方法：
      • 双击下载的 .mobileprovision 文件。Xcode 会自动导入。
      • 将文件拖动到 Xcode Dock 图标上。
      • 在 Xcode 的 Settings (or Preferences) > Accounts > [您的 Apple ID] > Manage Certificates... 中，或在 Settings (or Preferences) > Accounts > [您的 Apple ID] > Download Manual Profiles (对于自动管理的账号) 中查看或下载。对于 Manual Signing，最好双击导入确保其在正确的位置。

步骤 4: 检查 Keychain Access (钥匙串访问)

钥匙串是存储证书和私钥的地方，这是签名过程的关键。

  1. 打开 Keychain Access: 应用程序 > 实用工具 > 钥匙串访问。
  2. 选择钥匙串: 通常，签名所需的证书和私钥存储在 login 钥匙串中。确保选择了正确的钥匙串。
  3. 筛选项目: 在左下角选择 Certificates，并在搜索框中输入您的公司名称或证书名称（如 “Apple Development”）。
  4. 查找证书:
    • 找到您期望用于签名的 Apple Development 或 Apple Distribution 证书。
    • 检查证书的状态：是否显示为有效的绿色对勾？是否有红色的叉号表示无效？
    • 检查私钥: 在证书条目下方，应该有一个小的展开箭头。展开后，您应该看到一个带有私钥图标的条目，名称与您的证书名称相同。这是一个最常见的问题来源：找不到匹配的私钥！ 如果没有私钥，即使有证书，您也无法进行签名。
    • 信任设置: 右键点击证书，选择 Get Info。展开 Trust 部分。通常，所有信任设置都应该设置为 Use System Defaults。如果这里被手动更改过，可能会导致问题。
  5. 查找私钥 (直接筛选): 在左下角选择 Keys，搜索相关名称。找到与您的证书名称匹配的私钥。私钥图标是一个小小的密钥符号。
  6. 检查私钥访问权限: 右键点击私钥，选择 Get Info。切换到 Access Control 选项卡。
    • 确保选择了 Allow all applications to access this item，或者列表中明确包含了 /usr/bin/codesign。如果需要密码才能访问，codesign 命令可能会失败。通常情况下，设置为 Allow all applications... 是最简单的，但在企业环境中可能需要更严格的设置。如果这里设置了需要确认，签名时应该弹出对话框，但有时对话框可能被隐藏或超时。
  7. 处理重复项: 有时，钥匙串中可能存在同一个证书或私钥的多个副本。这可能导致 codesign 命令混淆。建议删除所有无效、过期或重复的证书和私钥（小心操作，不要删除团队其他成员的证书或公司共享的证书）。在删除之前，最好导出（Export）一份备份 (File > Export Items...)。
  8. 从其他 Mac 导入证书/私钥: 如果您是从另一台 Mac 迁移开发环境，并且只导出了证书 (.cer 文件)，但没有导出包含私钥的 Personal Information Exchange (.p12) 文件，您将无法签名。您需要回到拥有原始私钥的 Mac 上，将证书和私钥一起导出为 .p12 文件 (在钥匙串访问中选中证书和其关联的私钥，File > Export Items...，选择 .p12 格式)，然后在新的 Mac 上导入这个 .p12 文件（双击即可导入到钥匙串）。

步骤 5: 检查 Entitlements 和 Capabilities

项目启用的 Capabilities（如 Push Notifications, App Groups, Keychain Sharing 等）需要对应的 Provisioning Profile 包含相应的 Entitlements。

  1. 在 Xcode 中检查 Capabilities: 在 Target 设置中，进入 Signing & Capabilities 选项卡。查看您为应用添加的所有 Capabilities。
  2. 在 Apple Developer Portal 中检查 Provisioning Profile: 找到您使用的 Provisioning Profile，查看它包含的 Enabled Services (Entitlements)。确保 Portal 中 Profile 启用的 Capabilities 与 Xcode 项目中添加的 Capabilities 相符。
  3. 重新生成 Provisioning Profile: 如果不匹配，您需要在 Developer Portal 中编辑 Provisioning Profile 关联的 App ID，勾选或取消勾选相应的服务，然后更新并重新生成 Profile。下载新的 Profile 并导入到 Mac 中。
  4. 检查 Entitlements 文件: 项目中可能有一个 .entitlements 文件。确保其中的键值对与您期望的 Capabilities 和 Provisioning Profile 相符。Xcode 通常会自动管理这个文件，但在手动配置或处理旧项目时可能需要手动检查。

步骤 6: 检查 Embedded Frameworks 和 Dependencies

如果您的项目使用了 Embedded Frameworks、静态库、动态库或通过 CocoaPods/Carthage 添加的依赖，它们的签名状态也会影响主应用的签名。

  1. 检查 Embedded Binaries/Frameworks: 在 Target 设置的 General 选项卡中，查看 Frameworks, Libraries, and Embedded Content 部分。确保列出的所有 Embedded Binaries 都设置了正确的 Embed & Sign 方式。
  2. 检查依赖项目的签名设置: 如果您是将另一个本地项目作为依赖添加到您的工作区 (Workspace) 中，确保那个依赖项目的签名设置也是正确的。
  3. CocoaPods/Carthage: 如果使用 CocoaPods，运行 pod install 或 pod update 后，Pods 项目中的签名设置可能会被修改。检查 Pods 项目及其 Target 的 Build Settings，确认签名设置是否正确。Podfile 中有时会包含 post_install 脚本，这些脚本可能会影响签名设置，检查这些脚本是否有问题。尝试删除 Pods 文件夹和 Podfile.lock 文件，然后重新运行 pod install。对于 Carthage，确保拷贝到项目中的 Frameworks 是正确签名的。

步骤 7: 清除 Apple ID 账户信息和本地签名资产 (谨慎操作)

如果以上步骤都无法解决问题，或者您怀疑本地的签名资产（证书、私钥、Profile）存在混乱，可以尝试清除它们并重新导入。执行此步骤前请三思，确保您有能力重新获取所有必需的签名资产，特别是如果您在团队环境中工作，请咨询团队其他成员或管理员。

  1. 移除 Xcode 中的 Apple ID 账户: 在 Xcode > Settings (or Preferences) > Accounts 中，选择您的 Apple ID，然后点击左下角的 - 按钮移除账户。
  2. 清理钥匙串中的签名资产:
    • 打开 Keychain Access。
    • 在 login 钥匙串中，搜索您的公司名称或 “Apple Development”, “Apple Distribution” 等关键词。
    • 非常小心地 删除所有与您的开发者账号相关的 Apple Development/Distribution 证书及其关联的私钥。
    • 同时删除可能存在的重复或过期的证书/私钥。
    • 在执行删除前，强烈建议导出所有重要的证书和私钥作为备份。
  3. 清理本地 Provisioning Profile 文件夹: Provisioning Profile 文件存储在本地目录中。您可以手动删除它们。
    • 打开 Finder。
    • 在菜单栏选择 Go > Go to Folder... (快捷键 Shift + Command + G)。
    • 输入路径 ~/Library/MobileDevice/Provisioning Profiles/ 并前往。
    • 这个文件夹包含您在 Mac 上安装的所有 Provisioning Profile (.mobileprovision 文件)。它们的名称是 UUID。您可以按日期排序来查找最近安装的。
    • 删除与您的项目或 Apple ID 相关的 Provisioning Profile 文件。如果您不确定，可以全部删除，因为后续可以重新下载。
  4. 重新添加 Apple ID 账户: 在 Xcode > Settings (or Preferences) > Accounts 中，点击左下角的 + 按钮，重新添加您的 Apple ID。
  5. 重新导入签名资产:
    • 使用 Automatic Signing: 添加账户后，Xcode 会尝试自动下载必要的证书和 Provisioning Profile。在 Accounts 窗口中，选择您的 Apple ID，点击 Manage Certificates... 验证证书是否已下载。
    • 使用 Manual Signing: 您可能需要从 Apple Developer Portal 重新下载证书 (.cer) 和 Provisioning Profile (.mobileprovision) 文件，然后双击它们导入到钥匙串和 Xcode。如果您有 .p12 文件（包含私钥），导入 .p12 文件即可同时导入证书和私钥。

步骤 8: 检查系统权限和文件权限

codesign 命令需要足够的权限来访问钥匙串和项目文件。

  1. 钥匙串访问权限: 如步骤 4 中所述，检查私钥的访问控制设置。如果设置为 Ask When Using 或只允许特定应用访问，可能会弹出密码提示框，或者如果设置错误，codesign 会直接失败。确保 codesign 有权限访问。
  2. 项目文件权限: 确保您的用户账户对项目文件夹及其内容有读写权限。这通常不是问题，除非您是从其他用户账户复制项目或存在特定的文件权限设置。
  3. Xcode Command Line Tools: 确保 Xcode 的命令行工具已正确安装并指向当前使用的 Xcode 版本。打开终端，运行 xcode-select --print-path，确认路径是否指向您安装 Xcode 的位置（通常是 /Applications/Xcode.app/Contents/Developer）。如果路径不正确或工具未安装，运行 xcode-select --install。

步骤 9: 查看详细的构建日志

当 command codesign failed 发生时，Xcode 的构建日志会提供更多详细信息，这对于定位具体原因至关重要。

  1. 打开 Report Navigator: 在 Xcode 的左侧导航栏中选择最右边的图标 (Report Navigator)。
  2. 选择最近的构建失败: 找到导致错误的构建尝试（通常是红色的感叹号）。
  3. 展开 Build 步骤: 展开构建步骤，找到 CodeSign 或 Signing 相关的步骤。
  4. 查看详细输出: 展开 CodeSign 步骤，向下滚动查看完整的命令调用和错误输出。这里会显示 codesign 命令执行时具体的错误信息，例如“certificate has expired”, “CSSMERR_TP_NOT_TRUSTED”, “SecKey not found”, “no identity found” 等。这些详细信息可以直接指出问题所在（证书过期、找不到私钥、信任问题等），帮助您更快速地定位到上述某个步骤。

步骤 10: 其他不常见的问题

  • macOS 版本: 确保您的 macOS 版本与您使用的 Xcode 版本以及您尝试构建的应用类型（特别是新的 SDK 或设备）兼容。
  • Xcode 版本: 确保您使用的 Xcode 版本不是 Beta 版（除非您清楚其限制）并且是稳定版本。有时升级 Xcode 会解决问题，有时则可能引入新的签名问题（尽管不常见）。考虑升级或降级 Xcode。
  • 网络连接: 在验证证书、下载 Profile 或使用 Automatic Signing 时，Xcode 需要连接到 Apple 服务器。确保您的网络连接正常，没有防火墙或代理问题阻止连接到 apple.com 或 developer.apple.com。
  • 系统时间: 确保您的 Mac 系统时间是准确的。不正确的系统时间可能导致证书验证失败。
  • 清理 Derived Data: 除了清理 Build Folder，有时清理整个 Derived Data 目录也有帮助。这是一个更彻底的清理。关闭 Xcode，然后删除 ~/Library/Developer/Xcode/DerivedData/ 目录下的内容（或您在 Xcode Preferences 中指定的 Derived Data 位置）。

4. 预防措施

虽然 command codesign failed 错误令人头疼，但采取一些预防措施可以减少其发生的频率：

  • 定期检查证书和 Profile 的有效期: 在 Apple Developer Portal 中设置日历提醒或定期登录检查。
  • 妥善保管您的私钥: 在迁移开发环境时，务必导出包含私钥的 .p12 文件并安全备份。
  • 使用明确的签名策略: 在团队中统一使用 Automatic Signing 或 Manual Signing，并确保所有成员了解如何正确配置。
  • 及时更新 Xcode 和 macOS: Apple 会修复签名相关的 Bug 并改进流程。
  • 理解您的签名资产: 清楚您的团队有哪些证书、它们的用途以及它们与哪些 Provisioning Profile 关联。
  • 保持 Bundle Identifier 和 Capabilities 与 Profile 一致: 在修改项目设置时，同步更新 Apple Developer Portal 中的 App ID 和 Profile。

总结

command codesign failed 错误是 Xcode 开发中的一个常见障碍，但它通常是由于证书、私钥、Provisioning Profile 或 Xcode 项目配置中的某个环节不匹配或无效导致的。解决这个问题的关键在于：

  1. 理解代码签名的原理和组成部分。
  2. 从简单的检查开始，逐步深入。
  3. 系统性地检查 Xcode 的签名设置、Apple Developer Portal 中的资产以及本地的钥匙串访问。
  4. 利用 Xcode 的构建日志获取详细的错误信息。
  5. 耐心和细致地排查每一个可能的环节。

通过遵循本文提供的详细步骤，您应该能够有效地诊断并解决绝大多数 command codesign failed 错误，确保您的应用能够顺利地进行签名、构建、运行和发布。记住，在遇到问题时保持冷静，并按照逻辑顺序一步步排查，最终会找到问题的根源。

发表评论

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

滚动至顶部