command phasescriptexecution failed 遇到 nonzero exit code 怎么办？ – wiki基地

作者： /

深入解析与解决 Xcode 构建错误：command phasescriptexecution failed with nonzero exit code

在 iOS 或 macOS 应用开发过程中，使用 Xcode 进行构建（Build）是日常工作。然而，开发者常常会遇到各种构建错误，其中一个非常常见且令人头疼的问题就是 command phasescriptexecution failed with nonzero exit code。这个错误信息本身看似简洁，实则隐藏了各种底层脚本执行失败的复杂原因。理解这个错误、知道如何定位问题并有效解决，是每个 Xcode 开发者必备的技能。

本文将详细解析这个错误信息的含义、常见触发场景、深层原因以及一套系统化的故障排除与解决方案。我们将一步步揭示如何从嘈杂的构建日志中找到真正的“罪魁祸首”，并提供针对不同情况的具体修复建议。

1. 什么是 command phasescriptexecution failed with nonzero exit code？

首先，让我们拆解这条错误信息：

  • command phasescriptexecution failed: 这表明 Xcode 在执行一个“阶段脚本”（Phase Script Execution）时失败了。在 Xcode 的构建过程中，包含多个按顺序执行的“构建阶段”（Build Phases），例如编译源代码（Compile Sources）、复制资源（Copy Bundle Resources）、链接库（Link Binary With Libraries）等。其中一个重要的阶段就是“运行脚本”（Run Script）阶段，允许开发者执行自定义的 Shell 脚本或其他可执行文件，以完成一些特定任务，比如：

    • 管理依赖（Cocoapods, Carthage）
    • 代码生成（R.swift, SwiftGen）
    • 代码风格检查和格式化（SwiftLint, Clang-Format）
    • 自动化版本号或构建号的更新
    • 文件处理、资源优化、代码混淆等
    • 签名相关的后期处理
      这个错误就发生在执行这些自定义脚本的过程中。

  • with nonzero exit code: 在 Unix/Linux 系统中（macOS 基于此），当一个程序或脚本执行完毕时，会返回一个“退出码”（Exit Code）。按照惯例：

    • 退出码为 0 表示程序或脚本成功完成，没有错误。
    • 退出码为非零值（例如 1, 2, 127 等）表示程序或脚本执行过程中发生了错误。不同的非零值可能代表不同的错误类型，但对于 Xcode 而言，只要不是 0，就意味着脚本执行失败。

因此，整个错误信息的含义是：“Xcode 在执行某个自定义的构建阶段脚本时，该脚本未能成功完成，并返回了一个表示失败的非零退出码。”

这个错误本身并 不是 脚本失败的根本原因，它只是一个 结果。真正的错误信息往往隐藏在脚本执行过程中输出的日志里，我们需要通过分析这些日志来找出脚本为何失败。

2. Phase Script Execution 阶段在哪里？

在 Xcode 中，你可以在你的 Target 设置中找到“Build Phases”选项卡。这里列出了项目构建过程中所有的阶段。你通常会看到一个或多个名为“Run Script”的阶段。command phasescriptexecution failed 错误就与这些“Run Script”阶段中的某一个相关。错误信息通常会包含一个标识符，帮助你确定是哪个具体的脚本失败了，例如：

Command PhaseScriptExecution failed with a nonzero exit code
The following build commands failed:
PhaseScriptExecution [CP] Check Pods Manifest.lock /Users/.../DerivedData/Build/Intermediates.noindex/.../PhaseScriptExecution/[CP]\ Check\ Pods\ Manifest.lock.sh
(1 failure)

这里 [CP] Check Pods Manifest.lock 就是失败的脚本阶段的名称。

3. 为什么会发生 nonzero exit code？常见原因分析

脚本执行失败的原因多种多样，通常归结为以下几类：

3.1. 脚本本身的语法或逻辑错误

  • Shell 语法错误: 脚本中可能存在 Typos、错误的命令、不匹配的引号、括号等 Shell 语法错误。
  • 命令不存在 (Command Not Found): 脚本中调用的某个命令（如 swiftlint, carthage, node, python 等）在 Xcode 构建环境的 PATH 中找不到。这通常是由于该工具未安装，或者安装位置不在系统或 Xcode 已知的 PATH 中。
  • 文件或目录不存在 (No Such File or Directory): 脚本试图访问某个文件或目录，但该路径不正确或文件/目录不存在。这可能是由于路径硬编码错误、相对于错误的工作目录、或者前一个构建阶段未能生成预期的文件。
  • 权限问题 (Permission Denied): 脚本没有执行某个文件、读取某个文件或写入某个目录的权限。Xcode 构建过程通常以当前用户身份运行，但某些特定目录或文件可能权限受限。
  • 脚本逻辑错误: 脚本中的条件判断不正确、循环执行失败、调用其他程序失败但未 properly handle 错误等。例如，一个依赖外部命令的脚本，如果外部命令失败，脚本也应该以非零退出码退出。

3.2. 外部依赖问题

许多脚本依赖于外部工具或库：

  • Cocoapods: pod install 未运行、Podfile.lock 文件损坏或与项目不匹配、Pods 目录或生成的文件缺失。Cocoapods 添加的 Run Script Phase (如 [CP] Check Pods Manifest.lock, [CP] Embed Pods Products, [CP] Copy Pods Resources) 是 nonzero exit code 的常见来源。
  • Carthage: Carthage frameworks 未正确构建或复制。carthage build 或 carthage update 可能需要先运行。
  • SwiftLint, R.swift, SwiftGen 等代码生成/分析工具: 工具未安装、版本不兼容、配置文件错误、或者它们在执行过程中遇到了问题（如解析文件失败）。
  • Node.js, Python, Ruby 脚本: 如果 Run Script Phase 是执行这些语言的脚本，那么相应的运行时环境和依赖模块必须已安装且可在 PATH 中找到。

3.3. Xcode/构建环境问题

  • 缓存问题: Xcode 的构建缓存（Derived Data）可能损坏，导致构建过程中的中间文件不正确或缺失。
  • 环境变量问题: 脚本依赖于 Xcode 设置的环境变量（如 SRCROOT, BUILT_PRODUCTS_DIR, CONFIGURATION_BUILD_DIR 等），但这些变量在执行时值不正确，导致脚本使用了错误的路径。
  • Shell 环境不一致: Xcode 执行脚本的环境可能与你在终端中手动执行时的环境不同，特别是关于 PATH 和其他环境变量。
  • Xcode 版本或配置不兼容: 项目配置与当前 Xcode 版本不兼容，或者某些设置影响了脚本的执行。
  • M1/Intel 兼容性问题: 在 Apple Silicon (M1/M2/M3) Mac 上，如果脚本依赖于 Rosetta 运行的命令行工具，或者脚本本身需要指定架构执行，可能会出现问题。

3.4. 资源限制

  • 磁盘空间不足: 脚本尝试写入文件但磁盘已满。
  • 内存不足: 脚本或其调用的工具消耗过多内存导致进程被终止。

4. 系统化的故障排除与解决方案

解决 command phasescriptexecution failed with nonzero exit code 错误的关键在于：找到脚本失败时输出的实际错误信息。 这个信息不会直接显示在红色错误提示行，而是隐藏在详细的构建日志中。

以下是一套推荐的故障排除步骤：

步骤 1: 定位失败的构建阶段和详细日志

这是解决问题的 最关键一步。

  1. 打开 Xcode 的 Build Navigator: 在 Xcode 窗口的左侧导航栏中，选择第四个图标（像一个报纸或日志）。这将打开 Build Navigator。
  2. 找到失败的构建: 在 Build Navigator 中，通常最新的构建记录在顶部。找到标有红色感叹号的失败构建记录。
  3. 展开失败的步骤: 点击失败构建记录旁边的三角形或箭头以展开它。继续展开直到你看到标有红色感叹号的 PhaseScriptExecution 步骤。
  4. 查看详细日志: 选择这个失败的 PhaseScriptExecution 步骤。在 Xcode 窗口的主区域或底部区域（取决于你的布局）会显示这个步骤的详细日志输出。
  5. 查找红色错误信息: 在详细日志中，向上滚动，仔细查找红色的错误信息。这些红色行通常就是导致脚本以非零退出码退出的具体原因。常见的错误信息包括 error: ..., command not found, No such file or directory, Permission denied, 脚本语言（如 Ruby, Python, Swift）的错误堆栈等。

技巧:
* 日志可能非常长，可以使用日志查看区域右上角的搜索框来查找关键词，例如 error, failed, No such, Permission, command not found 等。
* 有时，真正的错误信息可能出现在脚本输出的 最后几行，紧接在脚本尝试退出之前。
* 在日志查看区域，你通常可以右键点击选择 “Expand All Transcripts” 来展开所有步骤的详细输出，然后慢慢查找。
* 你也可以右键点击失败的构建步骤，选择 “Reveal in Log File” 在外部文本编辑器中打开完整的构建日志文件，这有时更容易搜索和分析。

找到具体的错误信息是解决问题的前提。 例如，如果你在日志中看到 command not found: swiftlint，你就知道问题是 swiftlint 命令找不到；如果你看到 No such file or directory: /path/to/some/file，你就知道是某个文件路径不对。

步骤 2: 理解失败的脚本

一旦找到了具体的错误信息，下一步是确定是哪个脚本失败了，以及这个脚本是做什么的。

  1. 确定脚本名称: 失败的 PhaseScriptExecution 步骤的名称通常会在日志中显示（如前面的 [CP] Check Pods Manifest.lock）。
  2. 在 Build Phases 中找到脚本: 打开你的 Target 设置，切换到 “Build Phases” 选项卡。查找与日志中名称匹配的 “Run Script” 阶段。
  3. 查看脚本内容: 点击找到的 “Run Script” 阶段，展开它。你可以看到脚本的 Shell 类型（/bin/sh, /bin/bash, /usr/bin/ruby 等）和脚本的具体内容（通常在一个大的文本框里）。

通过阅读脚本内容，结合脚本名称，你应该能大致了解这个脚本的目的（例如，检查 Pods 依赖，运行 SwiftLint，复制文件等）。这有助于你理解为什么会发生之前的错误。

步骤 3: 针对具体错误信息进行排查和修复

根据在步骤 1 中找到的具体错误信息，采取相应的修复措施：

场景 1: command not found

  • 问题: 脚本试图执行一个命令，但系统找不到这个命令的执行文件。
  • 原因:
    • 该命令行工具未安装。
    • 该工具已安装，但其安装路径不在 Xcode 构建环境的 PATH 环境变量中。
  • 解决方案:
    • 安装工具: 使用相应的包管理器安装缺失的工具（例如，使用 Homebrew 安装 swiftlint 或 carthage，使用 gem install 安装 Ruby gems，使用 pip install 安装 Python 包，使用 npm install -g 安装 Node.js 工具）。
    • 检查 PATH: 确保安装的工具的执行文件所在的目录位于系统的 PATH 环境变量中。有时，通过某些途径安装的工具可能不会自动添加到标准 PATH。在 Run Script Phase 中，Xcode 的 PATH 可能比你的终端 PATH 要简单。
    • 使用绝对路径: 如果你知道工具的准确安装位置，可以在脚本中直接使用该工具的绝对路径，而不是仅仅使用命令名。例如，/opt/homebrew/bin/swiftlint 而不是 swiftlint。这可以避免 PATH 问题，但可能使得脚本不够灵活。一个更好的方法是在脚本开头显式地设置 PATH，或者在调用命令前先检查其是否存在（使用 which 命令）。
    • 针对 Cocoapods/Carthage: 如果是 pod 或 carthage 命令找不到，确保你已经正确安装了 CocoaPods/Carthage，并且它们在 PATH 中。有时需要使用 sudo gem install cocoapods 或 brew install carthage。

场景 2: No such file or directory

  • 问题: 脚本试图访问某个文件或目录，但它不存在。
  • 原因:
    • 脚本中的路径错误（硬编码错误、相对路径错误）。
    • 前一个构建阶段未能生成这个文件或目录。
    • 文件或目录确实被意外删除或移动了。
  • 解决方案:
    • 检查路径: 仔细检查脚本中涉及的路径。Xcode 提供了一些有用的环境变量，如 SRCROOT (项目根目录), BUILT_PRODUCTS_DIR (构建产物目录), CONFIGURATION_BUILD_DIR (当前配置的构建产物目录), PODS_ROOT (Pods 目录) 等。尽量使用这些变量来构建路径，而不是硬编码。例如，使用 ${SRCROOT}/path/to/your/file。
    • 确认文件存在: 在终端中使用 ls /path/to/the/file_or_directory 命令来验证该路径下文件或目录是否存在。注意在终端中模拟 Xcode 的环境，确保你在正确的当前工作目录（通常是项目根目录或脚本所在目录）下执行检查。
    • 检查前置步骤: 如果该文件是由前面的构建阶段或另一个脚本生成的，检查那个阶段是否成功执行，或者是否存在错误。
    • 清理构建目录: 有时旧的构建缓存会导致问题。执行 Product > Clean Build Folder (Shift + Command + K) 可以清除 Derived Data，迫使 Xcode 重新生成中间文件。

场景 3: Permission denied

  • 问题: 脚本没有执行某个文件、读取某个文件或写入某个目录的权限。
  • 原因:
    • 脚本本身没有执行权限。
    • 脚本试图写入一个没有写入权限的目录。
    • 脚本试图读取一个没有读取权限的文件。
  • 解决方案:
    • 检查文件权限: 在终端中使用 ls -l /path/to/the/file_or_directory 命令查看相关文件或目录的权限。例如，-rwxr-xr-x 表示所有者有读、写、执行权限。
    • 修改权限: 如果权限不足，可以使用 chmod 命令修改。例如，chmod +x /path/to/the/script_file 给脚本添加执行权限。chmod -R +w /path/to/the/directory 给目录及其内容添加写入权限。
    • 检查父目录权限: 确保脚本需要操作的目录及其所有父目录都允许 Xcode 构建用户访问。

场景 4: Cocoapods 相关脚本失败

  • 问题: 错误信息中包含 [CP] 前缀的脚本失败，例如 [CP] Check Pods Manifest.lock, [CP] Embed Pods Products, [CP] Copy Pods Resources。
  • 原因:
    • pod install 或 pod update 未运行或未成功完成。
    • Podfile.lock 文件与当前项目状态不符或已损坏。
    • Pods 目录 (Pods/) 不完整或损坏。
    • Cocoapods 版本与项目要求不符。
    • 在 M1/Apple Silicon Mac 上，可能存在架构兼容性问题。
  • 解决方案:
    • 重新安装 Pods: 在终端中进入项目根目录（Podfile 所在的目录），运行 pod install。如果网络有问题或依赖有更新，可以尝试 pod update。
    • 清理 Pods 缓存: 有时需要清理 Cocoapods 的缓存。运行 pod deintegrate，然后删除 Podfile.lock 和 Pods 目录，再运行 pod install。
    • 检查架构: 在 Apple Silicon Mac 上，如果你的某些 Pods 是为 Intel 架构构建的，或者存在兼容性问题，可能需要使用 Rosetta 运行 pod install。尝试 arch -x86_64 pod install。
    • 检查 Podfile 和 Podfile.lock: 确保这些文件没有手动修改错误，并且 Podfile.lock 与当前安装的 Pods 一致。
    • 检查 Xcode 版本: 确保你使用的 Xcode 版本与 Pods 生成的项目文件兼容。

场景 5: Carthage 相关脚本失败 (carthage copy-frameworks)

  • 问题: Carthage 的 carthage copy-frameworks 脚本失败。
  • 原因:
    • Carthage dependencies 未构建 (carthage build 或 carthage update 未运行)。
    • 框架文件 (.framework) 不存在或路径错误。
    • 框架签名问题。
  • 解决方案:
    • 构建 Carthage 依赖: 在终端中进入项目根目录 (Cartfile 所在的目录)，运行 carthage update --use-xcframeworks --platform iOS (根据你的平台调整参数)。
    • 检查框架路径: 确认 Run Script Phase 中指定的框架路径是正确的，指向 Carthage 构建生成的框架文件。
    • 清理 Carthage 缓存: 删除 Carthage 目录和 Cartfile.resolved 文件，然后重新运行 carthage update。

6. 其他常见工具脚本失败 (SwiftLint, R.swift, SwiftGen 等)

  • 问题: 集成的代码分析或生成工具脚本失败。
  • 原因:
    • 工具本身未安装或版本错误。
    • 工具的配置文件错误或语法问题（例如 .swiftlint.yml）。
    • 工具在处理项目文件时遇到错误（例如，解析 Swift 代码失败，资源文件格式错误）。
  • 解决方案:
    • 安装/更新工具: 使用相应的包管理器（Homebrew, Mint, RubyGems 等）安装或更新工具到项目要求的版本。
    • 检查配置文件: 仔细检查工具的配置文件是否存在语法错误或逻辑问题。许多工具在命令行执行时会提供更详细的错误信息。
    • 手动运行工具: 在终端中，尝试在项目根目录或工具配置所在的目录手动运行该工具，观察其输出和错误信息。例如，运行 swiftlint 或 rswift generate。这通常能获得比 Xcode 构建日志更清晰的错误提示。
    • 检查文件输入: 确保工具需要处理的输入文件存在且格式正确。

7. 脚本内部逻辑错误或调用失败

  • 问题: 脚本本身语法正确，也能找到所有命令，但在执行过程中因为内部逻辑错误或调用的子命令失败而退出。
  • 原因: 脚本中的 if 判断错误、循环没有正常终止、调用的另一个脚本或程序返回了非零退出码但主脚本没有捕获并处理、使用了不兼容的 Shell 语法等。
  • 解决方案:
    • 在终端中模拟执行: 这是调试自定义脚本最有效的方法。
      • 打开终端，cd 到项目根目录（通常是 Xcode 运行脚本时的工作目录）。
      • 复制 Run Script Phase 中的脚本内容。
      • 手动设置脚本可能依赖的关键环境变量。在 Xcode 的 Run Script Phase 配置界面底部，你可以找到输入/输出文件和环境变量设置。常见的环境变量有 SRCROOT, BUILT_PRODUCTS_DIR, CONFIGURATION_BUILD_DIR 等。你可以通过在脚本中临时添加 echo $VARIABLE_NAME 来查看它们在 Xcode 中的值。然后在终端中用 export VARIABLE_NAME=value 的方式设置它们。
      • 将脚本内容粘贴到终端中执行，或者保存为 .sh 文件并执行（bash your_script.sh）。
    • 逐步调试脚本:
      • 在脚本开头添加 set -e：这会使得脚本在任何命令返回非零退出码时立即退出。这有助于定位是哪一行命令失败了。
      • 在脚本开头添加 set -x：这会使得 Shell 在执行每一行命令前先打印该命令及其参数。这对于跟踪脚本执行流程和变量展开非常有帮助。
      • 在脚本中添加 echo 语句：在关键步骤前后添加 echo "Executing step X..." 或 echo "Variable Y is: $Y" 来跟踪脚本执行进度和变量值。
      • 注释掉部分代码：通过注释掉脚本的一部分来隔离问题区域。
    • 检查子命令的退出码: 如果脚本调用了其他命令或脚本，并且这些子命令可能失败，确保你的主脚本检查了它们的退出码（例如使用 && 或 || 操作符，或者在 if 语句中检查 $? 变量）并根据需要以非零退出码退出。

步骤 4: 清理构建目录和 Derived Data

如果以上步骤都无法解决问题，或者你怀疑是 Xcode 内部的缓存问题，可以尝试彻底清理构建相关数据：

  1. 清理构建文件夹: 在 Xcode 菜单中选择 Product > Clean Build Folder (快捷键 Shift + Command + K)。
  2. 清理 Derived Data: 关闭 Xcode。在 Finder 中，前往 ~/Library/Developer/Xcode/DerivedData/ 目录。删除对应项目的文件夹。这个文件夹包含了项目的构建索引、中间文件和最终构建产物。注意： 删除 DerivedData 会丢失当前的索引，下次打开项目 Xcode 可能需要重新构建索引，这可能需要一些时间。
  3. 重新打开项目并构建: 重新打开 Xcode 项目，然后再次尝试构建。

步骤 5: 检查版本控制差异

如果项目之前可以正常构建，而现在出现问题，很可能是最近的某些改动引入了错误。

  1. 查看最近的提交: 使用 Git 或其他版本控制工具查看最近的提交记录。
  2. 比较代码差异: 对比当前有问题的版本与最后一个正常构建的版本之间的代码差异，特别是涉及 Run Script Phase 本身、Podfile, Cartfile, SwiftLint 配置、以及脚本操作的文件和目录。
  3. 回退测试: 可以尝试回退到上一个已知正常构建的版本，看看问题是否消失。这有助于确认问题是由最近的改动引入的。

步骤 6: 检查 Xcode 和 macOS 版本

有时，构建问题可能与 Xcode 版本或 macOS 版本有关。

  1. 检查兼容性: 确认你的项目、依赖库（Pods, Carthage 等）以及构建工具与当前使用的 Xcode 版本和 macOS 版本兼容。
  2. 更新或降级: 如果怀疑是版本问题，可以尝试更新 Xcode 或 macOS，或者在必要时使用旧版本的 Xcode（可以通过 Apple Developer 网站下载）。

5. 预防措施：如何编写更健壮的构建脚本

为了减少未来遇到 nonzero exit code 错误的可能性，编写构建脚本时应遵循一些最佳实践：

  • 使用 set -e: 在脚本的开头添加 set -e。这会使脚本在任何命令失败时立即退出，而不是继续执行可能导致更多错误或意外行为的后续命令。这也有助于快速定位问题。
  • 使用 set -x 进行调试: 在调试阶段使用 set -x 来打印执行的每一行命令，完成后再移除。
  • 检查命令是否存在: 在调用可能不存在的命令前，可以使用 command -v your_command >/dev/null 2>&1 || { echo >&2 "Error: your_command is not installed."; exit 1; } 这样的结构来检查命令是否存在，并在不存在时输出友好错误信息并退出。
  • 使用绝对路径或基于环境变量的路径: 避免硬编码相对路径。利用 Xcode 提供的环境变量（SRCROOT, BUILT_PRODUCTS_DIR 等）来构建健壮的路径。
  • 正确处理错误: 对于可能会失败的关键命令，显式检查其退出码 ($?) 并根据需要采取行动或退出。
  • 输出有用的日志信息: 在脚本的关键步骤添加 echo 语句，输出正在执行的任务或重要的变量值，这有助于在构建日志中跟踪脚本的执行。
  • 将复杂逻辑放入单独的文件: 如果脚本很长或包含复杂的逻辑，考虑将其写入一个单独的 .sh 文件，然后在 Run Script Phase 中调用该文件（记得给文件执行权限）。这样更易于管理和调试。
  • 指定 Shell: 在 Run Script Phase 中明确指定使用的 Shell（如 /bin/bash）。在脚本文件开头也添加 Shebang（#!/bin/bash）。确保使用的 Shell 特性在目标环境中可用。
  • 版本控制脚本: 将你的构建脚本（特别是单独的文件）纳入版本控制，以便追踪修改和回滚。

6. 总结

command phasescriptexecution failed with nonzero exit code 是一个在 Xcode 开发中非常常见的错误，它指示某个构建阶段的脚本执行失败。这个错误信息本身是一个结果，真正的失败原因隐藏在详细的构建日志中。

解决这个问题的核心在于：

  1. 定位并仔细分析详细的构建日志，找到脚本输出的红色错误信息。
  2. 识别失败的脚本 及其在项目中的位置。
  3. 理解脚本的目的，以及失败的错误信息可能与脚本的哪部分相关。
  4. 根据具体的错误信息（如 command not found, No such file, Permission denied 等）采取有针对性的修复措施，包括安装依赖、检查路径、修改权限、清理缓存等。
  5. 对于自定义脚本，在终端中模拟执行并逐步调试 是最有效的方法。

通过掌握日志分析技巧和系统化的故障排除步骤，开发者可以快速定位并解决这类问题，提高开发效率。同时，遵循编写健壮脚本的最佳实践可以从源头上减少这类错误的发生。

记住：日志是你的朋友！ 花时间仔细阅读构建日志，它会告诉你脚本为何失败。

希望这篇文章能帮助你下次面对 command phasescriptexcution failed with nonzero exit code 错误时不再感到茫然，而是能够有条不紊地解决它。

发表评论

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

滚动至顶部