解决 command phasescriptexecution failed with a nonzero exit code 错误 – wiki基地

作者： /

深入剖析与解决 Xcode 错误：Command PhaseScriptExecution failed with a nonzero exit code

在 iOS 或 macOS 开发过程中，使用 Xcode 进行项目构建时，开发者可能会遇到各种各样的错误。其中一个非常常见且令人头疼的错误是 "Command PhaseScriptExecution failed with a nonzero exit code"。这个错误信息本身比较泛泛，并没有直接指出问题的根源，只是告诉你“某个脚本执行失败了”，这使得定位和解决问题变得有些棘手。

本文将深入剖析这个错误产生的原因，提供一套系统性的诊断方法，并详细列举常见的解决方案，帮助你快速有效地解决这个问题，恢复项目的正常构建。

1. 理解错误信息：”Command PhaseScriptExecution failed with a nonzero exit code”

首先，我们需要理解这条错误信息中的各个部分代表什么含义：

  • Command: 指的是 Xcode 在构建过程中尝试执行的一个命令。
  • PhaseScriptExecution: 特指 Xcode 构建流程中的一个特定阶段——“运行脚本阶段”（Run Script Phase）。在这个阶段，Xcode 会执行项目配置中定义的或由某些工具（如 Cocoapods, Carthage, SwiftLint 等）自动添加的 Shell 脚本。
  • failed: 表示该命令执行失败了。
  • with a nonzero exit code: 这是 Shell 脚本的标准行为。当一个脚本或程序成功执行完成时，它通常会返回一个退出码（exit code）为 0。如果执行过程中发生了错误，它会返回一个非零的退出码（例如 1）。所以，”nonzero exit code” 就是告诉你：运行脚本阶段的某个脚本执行时出错了。

简单来说，这条错误信息的意思就是：“在项目的构建过程中，有一个 Shell 脚本在执行时出错了，并且返回了一个非零的错误代码。”

2. 这个错误通常在哪里出现？

当你遇到这个错误时，它通常会出现在 Xcode 的 Build Log (构建日志) 中。在 Xcode 中，你可以通过以下方式查看构建日志：

  1. 在 Xcode 窗口的顶部菜单栏选择 View -> Navigators -> Report，或者使用快捷键 Cmd + 8 打开 Report Navigator。
  2. 在 Report Navigator 中，找到最近一次失败的构建（通常会有一个红色的感叹号标记）。
  3. 点击该构建记录，然后在右侧窗格中找到红色的错误信息。通常，这个 "Command PhaseScriptExecution failed with a nonzero exit code" 会出现在详细错误输出的 末尾。

关键点： 这个错误信息本身是结果，而不是原因。真正的错误原因通常隐藏在它 之前 的构建日志输出中。

3. 为什么会发生这个错误？常见原因分析

既然错误是由于某个脚本执行失败导致的，那么我们需要考虑是什么可能导致脚本执行失败。这个错误的常见原因包括但不限于：

  • 依赖管理工具问题 (Cocoapods/Carthage):
    • pod install 或 carthage update 没有成功运行，导致脚本依赖的文件（如 Pods 项目、Manifest.lock、生成的 Frameworks）不存在或不正确。
    • Cocoapods 的 Embed Pods Frameworks 或 Check Pods Manifest.lock 脚本执行失败。
    • Carthage 的 carthage copy-frameworks 脚本执行失败。
  • 第三方工具/脚本问题:
    • 项目使用了像 SwiftLint、ESLint、BuildPhases 之类的代码检查、格式化或自动化工具，它们的脚本执行失败。
    • 自定义的 Shell 脚本存在语法错误、逻辑错误、文件路径错误等。
  • 环境变量或路径问题:
    • 脚本依赖的某个命令行工具（如 pod、carthage、swiftlint、node、python 等）没有安装，或者虽然安装了，但其路径不在脚本执行时的环境变量 $PATH 中，导致找不到命令。
    • 脚本中使用了相对路径，但在 Xcode 的构建环境中执行时，当前工作目录与预期不符。
    • 某些环境变量（如 $SRCROOT, $BUILT_PRODUCTS_DIR）没有正确解析或值不正确。
  • 权限问题:
    • 脚本尝试访问或修改没有执行权限的文件或目录。
  • 文件或目录缺失:
    • 脚本尝试访问或操作一个不存在的文件或目录。这可能是由于上一步的构建失败、清理不彻底、或者依赖没有正确生成导致的。
  • 脚本内容错误:
    • 脚本内部逻辑错误，例如使用了未定义的变量、命令参数错误、条件判断失败等。
  • 缓存问题:
    • Xcode 的 Derived Data 或构建缓存损坏或过期，导致使用了错误的状态或旧的文件。
  • Xcode 版本或配置问题:
    • Xcode 版本与项目、Pods 或 Carthage 版本不兼容。
    • 项目的 Build Settings 中与脚本相关的配置有误。

4. 系统化诊断步骤：找到真正的错误源头

解决这个错误的关键在于：忽略表面的 “nonzero exit code” 信息，深入分析它之前的构建日志，找到导致脚本失败的 具体原因。

以下是建议的诊断步骤：

步骤 1：仔细检查构建日志 (Build Log)

这是最重要的一步。

  1. 打开 Report Navigator (Cmd + 8)，找到失败的构建。
  2. 展开失败的构建步骤，直到看到红色的错误信息。
  3. 向下滚动，找到包含 "Command PhaseScriptExecution failed with a nonzero exit code" 的那一行。
  4. 向上滚动！ 在这一行 之前 的输出中，寻找其他红色的错误信息、黄色的警告信息，或者脚本打印出来的任何错误提示。
    • 寻找类似 error: [具体的错误信息] 的行。
    • 寻找脚本工具本身的输出，例如 pod: command not found、swiftlint: [file]:[line]:[column]: error: [rule] [message]、No such file or directory 等。
    • 有时候，脚本会在执行失败前打印出它正在执行的命令或某些变量的值。

示例：

你可能会在日志中看到类似这样的输出，而 "Command PhaseScriptExecution failed with a nonzero exit code" 会出现在最后：

“`
… (其他构建输出) …
❌ Check Pods Manifest.lock
cd /Users/yourname/Projects/YourProject
/bin/sh -c \”/Users/yourname/Library/Developer/Xcode/DerivedData/YourProject-abcdef/Build/Intermediates.noindex/YourProject.build/Debug-iphonesimulator/YourProject.build/Script-XXXXXXXX.sh\”

diff: /Pods/Target Support Files/Pods-YourProject/Pods-YourProject.sh: No such file or directory
diff: /Pods/Manifest.lock: No such file or directory
error: The sandbox is not in sync with the Podfile.lock. Run ‘pod install’ to update the Pods sandbox.

Command PhaseScriptExecution failed with a nonzero exit code
“`

在这个例子中，日志清晰地指出了错误是 diff: No such file or directory 以及 error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' to update the Pods sandbox.。这就告诉你问题出在 Cocoapods，并且需要运行 pod install。

步骤 2：确定是哪个脚本/阶段失败了

在构建日志中，找到 "Command PhaseScriptExecution failed with a nonzero exit code" 上方，通常会看到正在执行的脚本阶段的名称。它可能是：

  • Run Script (可能是自定义脚本)
  • [CP] Check Pods Manifest.lock (Cocoapods)
  • [CP] Embed Pods Frameworks (Cocoapods)
  • [CP] Copy Pods Resources (Cocoapods)
  • carthage copy-frameworks (Carthage)
  • Run SwiftLint (SwiftLint)
  • 其他自定义名称的 Run Script Phase

这能帮助你缩小问题范围，知道是哪个工具或哪个自定义脚本出了问题。

步骤 3：检查对应的脚本内容

  1. 在 Xcode 的 Project Navigator 中，选择你的项目文件 (.xcodeproj) 或 Workspace 文件 (.xcworkspace)。
  2. 选择你的 Target。
  3. 切换到 Build Phases 选项卡。
  4. 找到步骤 2 中确定的那个脚本阶段。
  5. 展开该阶段，查看其中的 Shell 脚本内容。
    • 如果是 Cocoapods 或 Carthage 自动生成的脚本，通常不需要修改，问题可能在于依赖本身。
    • 如果是自定义脚本，仔细阅读脚本代码，检查是否有语法错误、路径问题、命令错误等。

步骤 4：考虑运行环境

记住，脚本是在 Xcode 的构建环境中执行的，这个环境可能与你在终端中直接执行脚本的环境有所不同（例如，环境变量 $PATH 可能不同）。

  • 脚本中引用的外部命令（如 pod, carthage, swiftlint）是否在 $PATH 中？你可以在脚本的开头临时添加一行 echo $PATH 来查看构建时的 $PATH。
  • 脚本中的相对路径是相对于哪个目录的？通常是项目根目录或者 Xcode 定义的特定变量（如 $SRCROOT）。

5. 常见解决方案和步骤

根据诊断步骤找到的线索，以下是一些针对常见原因的解决方案：

5.1 通用解决方案 (无论原因如何，可以先尝试)

这些步骤可以解决很多由缓存或环境引起的问题：

  1. Clean Build Folder: 在 Xcode 菜单栏选择 Product -> Clean Build Folder (或使用快捷键 Shift + Cmd + K)。这会删除大部分构建生成的文件。
  2. Delete Derived Data: Derived Data 包含构建的中间文件、索引等。有时候这里的数据会损坏。
    • 在 Xcode 菜单栏选择 File -> Project Settings... 或 Workspace Settings...。
    • 点击 Derived Data 旁边的灰色箭头按钮，这会打开 Finder 到 Derived Data 目录。
    • 关闭 Xcode。
    • 在 Finder 中，将你的项目对应的 Derived Data 文件夹移到废纸篓。
    • 重新打开 Xcode。
  3. Restart Xcode: 有时候简单地重启 Xcode 可以解决一些奇怪的问题。
  4. Restart Computer: 万能的重启大法，有时候能解决系统环境或后台进程引起的问题。

5.2 针对依赖管理工具 (Cocoapods / Carthage)

如果日志指向 Cocoapods 或 Carthage 相关的脚本：

  1. 运行 pod install 或 carthage update:
    • 打开终端，进入你的项目根目录（包含 Podfile 或 Cartfile 的目录）。
    • 运行 pod install (如果 Podfile 没有变化或者只想安装依赖)。
    • 运行 pod update (如果 Podfile 有变化或者想更新所有依赖到最新兼容版本)。
    • 运行 carthage update --platform iOS (或你的目标平台)。
    • 检查终端输出： 查看 pod install 或 carthage update 的输出，确保它们没有报错。如果这些命令本身就失败了，你需要先解决它们的问题（例如网络问题、语法错误、依赖冲突等）。
  2. 检查 .gitignore 文件: 确保 Pods 目录 (对于 Cocoapods) 或 Carthage 目录和 Cartfile.resolved 文件 (对于 Carthage) 没有 被 .gitignore 忽略提交，并且这些目录在你运行 pod install/carthage update 后确实存在且包含内容。
  3. 检查 Xcode 项目配置:
    • 对于 Cocoapods，确保你打开的是 .xcworkspace 文件而不是 .xcodeproj 文件。
    • 检查 Build Phases 中 Cocoapods/Carthage 相关的脚本阶段是否正确配置（输入/输出文件路径是否正确）。Cocoapods 通常会自动配置，但自定义设置可能会出错。

5.3 针对第三方工具/自定义脚本

如果日志指向 SwiftLint、ESLint 或其他自定义脚本：

  1. 检查工具是否安装及路径:
    • 在终端中尝试直接运行该命令，例如 swiftlint --version。如果命令找不到 (command not found)，说明该工具没有安装或不在系统的 $PATH 中。
    • 如果使用了 Homebrew (brew install swiftlint) 安装，其路径通常在 /usr/local/bin 或 /opt/homebrew/bin。
    • 确保 Xcode 构建环境中的 $PATH 包含了该工具的安装路径。你可以在脚本的开头加上 export PATH="/usr/local/bin:$PATH" 或工具实际安装路径来尝试。
    • 如果工具是通过 npm 或 gem 安装的，确保 Node.js 或 Ruby 环境正确，并且其 bin 目录在 $PATH 中。
  2. 检查工具的配置文件:
    • 许多工具（如 SwiftLint、ESLint）依赖于项目根目录下的配置文件（如 .swiftlint.yml, .eslintrc.js）。检查这些文件是否存在、语法是否正确、配置是否与你的项目兼容。
  3. 检查脚本内容:
    • 仔细阅读 Build Phases 中的脚本。它可能只是简单地调用一个外部命令，或者包含更复杂的逻辑。
    • 在脚本开头添加 set -e 和 set -x 可以极大地帮助调试：
      • set -e: 任何命令执行失败（返回非零退出码）都会立即终止脚本。
      • set -x: 在执行每一行命令之前，都会先打印出该命令及其参数。这能让你看到脚本实际执行了什么命令，以及传递的参数是什么。在调试完成后记得移除它们。
    • 在脚本中添加 echo 语句来打印变量值或执行进度，帮助定位问题。
  4. 手动运行脚本:
    • 将 Build Phases 中的脚本内容复制出来。
    • 打开终端，切换到你的项目根目录。
    • 尝试在终端中手动执行脚本内容。请注意，你可能需要手动设置一些 Xcode 环境变量（如 $SRCROOT, $BUILT_PRODUCTS_DIR 等），或者将脚本保存到一个 .sh 文件并通过 ./your_script.sh 执行。手动执行可以让你更直观地看到脚本的输出和错误信息。
  5. 检查脚本的输入/输出文件:
    • 在 Build Phases 中，检查脚本阶段的 “Input Files” 和 “Output Files” 设置。如果这些设置不正确，Xcode 可能会因为认为文件过时而强制运行脚本，或者因为找不到输入文件而导致脚本失败。确保列出的路径是正确的。

5.4 针对权限问题

如果日志中有权限相关的错误（如 Permission denied）：

  1. 检查脚本文件权限: 如果脚本是一个单独的文件（而不是直接写在 Build Phases 里），确保它有执行权限。在终端中使用 chmod +x /path/to/your/script.sh 命令添加执行权限。
  2. 检查脚本操作的文件/目录权限: 确保脚本尝试读写的文件或目录对执行该脚本的用户（通常是你的当前用户）有读写权限。

5.5 针对文件或目录缺失

如果日志提示 No such file or directory 或类似的错误：

  1. 确定缺失的是哪个文件/目录: 根据日志中的路径信息，找到具体缺失的文件或目录。
  2. 找出为什么会缺失:
    • 它应该是由上一个构建步骤或外部工具生成的吗？如果是，检查上一个步骤或外部工具是否执行成功（例如，Cocoapods/Carthage 是否运行成功）。
    • 脚本中的路径是否正确？是绝对路径还是相对路径？相对路径是否基于正确的当前工作目录？使用 echo $SRCROOT 或其他相关变量来确认路径是否解析正确。
    • 文件是否被意外删除或移动了？
  3. 重新生成缺失的文件/目录: 运行 pod install、carthage update 或其他生成该文件/目录的命令。

5.6 针对环境变量或路径问题

如果日志提示 command not found 或脚本行为异常：

  1. 检查 $PATH 变量: 在脚本开头添加 echo $PATH，查看 Xcode 构建时的 $PATH。
  2. 修正 $PATH: 如果工具路径不在 $PATH 中，可以在脚本开头显式地添加它，例如 export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"。
  3. 使用绝对路径: 在脚本中调用外部命令时，尽量使用其绝对路径，例如 /usr/local/bin/swiftlint 代替 swiftlint，可以避免 $PATH 的影响。使用 which swiftlint 在终端中可以找到工具的绝对路径。

6. 高级调试技巧

如果以上步骤未能解决问题，可以尝试更深入的调试：

  • 隔离问题脚本: 暂时禁用项目 Build Phases 中的其他 Run Script 阶段，只保留出问题的那个，看是否仍然报错。这有助于确定问题是否与其他脚本冲突。
  • 简化脚本: 如果是自定义脚本，逐步简化脚本内容，甚至只保留一行简单的 echo "Hello"，然后逐渐增加复杂性，定位是哪一部分代码导致了问题。
  • 查看 Xcode 环境变量: 在 Build Phases 中添加一个简单的脚本 env > ~/xcode_build_env.txt，构建后查看生成的文件，其中包含了 Xcode 构建时设置的所有环境变量，这对于理解脚本的执行环境非常有帮助。
  • 使用不同的 Shell: 默认情况下，Xcode 的 Run Script 可能会使用 /bin/sh 或 /bin/bash。你可以在脚本开头指定使用特定的 Shell，例如 #!/bin/bash 或 #!/bin/zsh，并确保脚本语法与所选 Shell 兼容。

7. 如何预防这个错误？

虽然错误难以完全避免，但可以采取一些措施降低其发生的频率：

  • 使用 .xcworkspace: 如果使用 Cocoapods，始终打开 .xcworkspace 文件。
  • 提交依赖管理生成的文件: 将 Podfile.lock (Cocoapods) 和 Cartfile.resolved (Carthage) 文件提交到版本控制，以确保团队成员使用相同的依赖版本。对于 Cocoapods，通常也建议提交 Pods 目录到版本控制（虽然这有争议，但可以避免初次克隆项目时需要运行 pod install 的问题，尤其是在 CI/CD 环境中）。
  • 标准化开发环境: 使用 Homebrew 或类似的工具管理命令行工具，并确保团队成员的环境一致。考虑使用脚本检查或设置 $PATH。
  • 测试自定义脚本: 在终端中充分测试自定义脚本，确保它们在各种情况下都能正常工作，并且处理好错误情况。
  • 清晰的日志输出: 在自定义脚本中，使用 echo 语句打印关键信息和错误，帮助未来调试。
  • 保持依赖更新: 定期更新 Cocoapods、Carthage、SwiftLint 等工具到最新稳定版本，并随之运行 pod update 或 carthage update。

8. 总结

“Command PhaseScriptExecution failed with a nonzero exit code” 错误是 Xcode 构建中常见的拦路虎。解决它的关键在于：

  1. 不要被错误信息本身吓倒。
  2. 立即去构建日志 (Build Log) 中向上查找，定位真正的错误原因。
  3. 确定是哪个脚本阶段出了问题。
  4. 根据脚本类型（依赖管理、第三方工具、自定义）和日志中的具体错误信息，采取相应的诊断和解决步骤。
  5. 利用 Clean Build Folder 和 Delete Derived Data 作为通用的初步尝试。
  6. 对于脚本本身的问题，利用 set -e 和 set -x 进行调试。

通过系统性的分析和耐心的排查，大多数情况下都可以成功解决这个错误。希望这篇详细的指南能帮助你高效地处理未来可能遇到的 "Command PhaseScriptExecution failed with a nonzero exit code" 问题。祝你构建顺利！

发表评论

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

滚动至顶部