修复 command phasescriptexecution failed 错误 (nonzero exit code) – wiki基地

作者： /

深入解析与解决：修复 Xcode 中的 Command PhaseScriptExecution failed (nonzero exit code) 错误

作为 iOS、macOS 或其他 Apple 平台开发者，使用 Xcode 进行构建时，Command PhaseScriptExecution failed with a nonzero exit code 这个错误信息无疑是令人头疼的拦路虎之一。它不像语法错误那样直接指出问题所在，而是笼统地告诉你：“某个脚本执行失败了”。这个错误可能由各种原因引起，从简单的权限问题到复杂的环境配置或第三方库集成冲突。

本文将深入解析这个错误，解释它为何发生，并提供一套系统性的、详细的故障排除方法，帮助你定位并解决问题。我们的目标是让你不仅能够修复当前的错误，还能理解背后的原理，以便将来遇到类似问题时能够游刃有余。

文章目录

  1. 什么是 PhaseScriptExecution 错误？
  2. 为什么会发生这个错误？常见的脚本类型
  3. 故障排除的核心策略：阅读日志
  4. 详细的故障排除步骤
    • 步骤 1：仔细阅读错误信息和构建日志 (这是最重要的！)
    • 步骤 2：清理构建目录 (Clean Build Folder)
    • 步骤 3：检查文件权限
    • 步骤 4：检查脚本路径和文件是否存在
    • 步骤 5：检查环境变量和路径 (PATH)
    • 步骤 6：针对常见的第三方库集成方案 (CocoaPods, Carthage, SPM)
    • 步骤 7：检查自定义构建脚本
    • 步骤 8：架构兼容性问题 (特别是 Apple Silicon / M1/M2/M3)
    • 步骤 9：考虑外部工具或依赖
    • 步骤 10：清理 Derived Data
    • 步骤 11：重启 Xcode 和你的电脑
    • 步骤 12：检查 Xcode 版本和项目设置
    • 步骤 13：寻求社区帮助
  5. 预防措施：如何减少此类错误的发生
  6. 总结

1. 什么是 PhaseScriptExecution 错误？

在 Xcode 的构建过程中，会经历多个“构建阶段”（Build Phases）。这些阶段按照特定的顺序执行，完成从源代码编译到最终产品打包的所有任务。常见的构建阶段包括：

  • Compile Sources (编译源代码)
  • Process Resources (处理资源文件)
  • Compile Assets (编译 Asset 目录)
  • Link Binary With Libraries (链接二进制文件与库)
  • Copy Files (拷贝文件)
  • Run Script (执行脚本)

PhaseScriptExecution 错误就发生在 Run Script 这个构建阶段。这个阶段允许开发者或第三方库（如 CocoaPods, Carthage）在构建过程中执行自定义的 shell 脚本。这些脚本可以用于各种目的，例如：

  • 处理文件 (如拷贝、修改)
  • 运行代码生成工具
  • 执行静态分析工具 (如 SwiftLint)
  • 嵌入 Frameworks
  • 拷贝资源 Bundle
  • 运行依赖管理工具的特定步骤

当 Xcode 尝试执行某个 Run Script 阶段的脚本时，如果该脚本由于任何原因未能成功完成（即返回了一个非零的退出码），Xcode 就会中断构建，并报告 Command PhaseScriptExecution failed with a nonzero exit code 错误。非零退出码是 Unix/Linux 系统中表示程序执行失败的约定。

2. 为什么会发生这个错误？常见的脚本类型

这个错误之所以常见且原因多样，是因为它可能发生在任何一个 Run Script 阶段。常见的导致此错误的脚本类型和场景包括：

  • CocoaPods 的脚本: CocoaPods 在 Podfile 配置后，会在项目中添加多个 Run Script 阶段，用于集成 Pods 的 Frameworks、资源、签名等。例如 [CP] Embed Pods Frameworks, [CP] Copy Pods Resources, [CP] Check Pods Manifest.lock 等。这些脚本失败通常与 Pods 安装、版本、架构或环境有关。
  • Carthage 的脚本: Carthage 也需要添加 Run Script 阶段来拷贝和嵌入它构建的 Frameworks。
  • Swift Package Manager (SPM) 的构建工具/插件: 虽然 SPM 的核心依赖管理与 Pods/Carthage 不同，但如果 SPM 包中包含构建工具或需要在构建过程中运行的脚本，也可能导致此问题。
  • 自定义构建脚本: 开发者自己添加的用于特定任务的脚本，例如自动化版本号管理、处理国际化文件、运行代码质量检查工具等。
  • Framework 的嵌入脚本: 有些第三方或内部 Framework 需要通过脚本的方式嵌入或处理。

由于错误发生在脚本执行层面，这意味着问题不在于你的 源代码 本身的语法或编译错误，而在于构建 流程 中的某个自动化步骤失败了。

3. 故障排除的核心策略：阅读日志

面对 Command PhaseScriptExecution failed 错误，最重要、最有效的第一步 永远是仔细阅读错误信息和构建日志。错误信息本身只是一个笼统的概括，但构建日志会包含脚本执行时的详细输出，包括：

  • Xcode 尝试执行的具体命令。
  • 脚本在执行过程中打印的标准输出 (stdout)。
  • 脚本在执行过程中打印的错误输出 (stderr)。
  • 脚本的退出码。

这些详细信息是诊断问题的关键线索。忽略日志，直接尝试各种“可能有效”的解决方案，往往会浪费大量时间，甚至可能引入新的问题。

4. 详细的故障排除步骤

接下来，我们将按照系统性的方法，从最常见、最容易解决的问题开始，逐步深入。

步骤 1：仔细阅读错误信息和构建日志 (这是最重要的！)

  • 定位错误: 在 Xcode 界面左侧的 Issue Navigator (导航器面板的第一个图标) 中找到这个错误。点击它，通常会在右侧的详细信息面板中显示更多内容。
  • 查看报告: 错误信息通常会指向构建报告 (Report Navigator)。点击 Xcode 菜单栏的 View -> Navigators -> Report (或使用快捷键 ⌘8) 打开 Report Navigator。找到最近一次失败的构建记录。
  • 展开详细信息: 在 Report Navigator 中，找到显示为红色的错误行，通常会是 PhaseScriptExecution [脚本名称] ...。点击该行旁边的展开箭头 (>)。
  • 查找命令和输出: 展开后，你会看到 Xcode 尝试执行的完整 shell 命令。在这条命令下方，通常会有 Output 部分。展开 Output 部分，仔细阅读里面的内容。
    • 关键信息: 寻找红色的错误信息、error 或 failed 等关键字。这些信息是脚本本身在执行过程中打印的，会告诉你具体是什么操作失败了。
    • 失败的命令: 确认是哪个具体的脚本或命令失败了。例如，如果是 CocoaPods 相关的错误，你可能会看到 /bin/sh -c ... Embed\ Pods\ Frameworks 这样的命令。
    • 上下文信息: 日志中可能包含文件路径、文件名、行号等信息，这些都能帮助你定位问题源头。

举例： 错误日志可能显示 /bin/sh -c ... [CP] Embed\ Pods\ Frameworks 执行失败，在输出中看到 /usr/local/bin/carthage: No such file or directory。这立刻告诉你，问题在于脚本尝试执行 carthage 命令，但系统找不到它。

投入足够的时间在这一步！ 很多时候，日志已经清晰地指明了原因。

步骤 2：清理构建目录 (Clean Build Folder)

这是 Xcode 故障排除中最常见的第一步，虽然不总是有效，但尝试一下无妨，因为它无害且快速。有时候，构建过程中产生的临时文件或缓存可能已损坏或过时。

  • 在 Xcode 菜单栏选择 Product -> Clean Build Folder (注意不是 Clean，Clean Build Folder 更彻底)。
  • 清理完成后，再次尝试构建。

步骤 3：检查文件权限

脚本文件本身或者脚本需要操作的文件可能没有足够的权限。特别是脚本文件本身需要有执行权限 (+x)。

  • 定位脚本文件: 如果日志指明了失败的脚本文件路径，使用 Finder 或终端检查其权限。
  • 检查执行权限: 在终端中使用 ls -l [脚本文件路径] 查看权限。如果权限中没有 x (例如 -rw-r--r--)，则表示没有执行权限。
  • 添加执行权限: 在终端中使用 chmod +x [脚本文件路径] 给脚本添加执行权限。
  • 检查操作文件的权限: 如果脚本是读写特定文件或目录，确保 Xcode（通常以当前用户身份运行）有足够的权限进行这些操作。

4. 检查脚本路径和文件是否存在

如果脚本尝试执行某个外部命令或访问特定文件，但该命令或文件不存在，脚本就会失败。

  • 检查日志中的路径: 日志通常会显示脚本尝试访问的文件或命令的完整路径。
  • 手动验证: 在终端中，使用 ls [路径] 来验证文件或目录是否存在。
  • 检查命令是否存在: 如果脚本调用了外部命令（如 swiftlint, rswift, node, python 等），在终端中尝试直接运行该命令，或者使用 which [命令名] 来检查该命令是否安装并且在系统的 PATH 中。

5. 检查环境变量和路径 (PATH)

构建脚本在 Xcode 的特定环境中执行，这个环境可能与你在终端中手动运行时的环境不同。特别是 $PATH 环境变量，它决定了 shell 在哪些目录中查找可执行命令。

  • Xcode 的 PATH: Xcode 的构建环境 $PATH 可能不包含你在终端中配置的所有路径（例如通过 .bash_profile, .zshrc 配置的自定义路径）。
  • 脚本依赖外部工具: 如果脚本依赖 Homebrew 安装的工具 (/usr/local/bin 或 /opt/homebrew/bin) 或其他不在默认系统路径的工具，可能会找不到。
  • 解决方案:
    • 在脚本开头设置 PATH: 在你的 Run Script 脚本的顶部显式地设置 $PATH 变量，包含所有必要的目录。例如：
      bash
      export PATH="/usr/local/bin:/opt/homebrew/bin:$PATH"
      # 然后再执行你的命令，如 swiftlint
      swiftlint
    • 使用命令的完整路径: 如果知道命令的绝对路径，直接在脚本中使用完整路径执行，而不是仅仅使用命令名。例如 /usr/local/bin/swiftlint。
  • 检查其他构建变量: 脚本中可能使用了 Xcode 的构建变量，如 $SRCROOT, $BUILT_PRODUCTS_DIR, $TARGET_BUILD_DIR 等。确保这些变量在使用时是正确的，并且指向期望的文件或目录。可以在脚本中添加 echo 语句来打印这些变量的值进行调试。

6. 针对常见的第三方库集成方案 (CocoaPods, Carthage, SPM)

许多 PhaseScriptExecution 错误与第三方库集成相关。

  • CocoaPods:
    • pod install 是否运行? 这是最常见的原因。每次 Podfile 或 Podfile.lock 更改后，必须在项目根目录运行 pod install。确保你打开的是 .xcworkspace 文件而不是 .xcodeproj 文件。
    • Pods 是否损坏或过时? 尝试清理 Pods 缓存并重新安装。
      bash
      pod cache clean --all
      # 在项目目录下
      pod deintegrate # 这一步会移除所有 Pods 集成设置
      pod install
    • 架构问题 (特别是 M1/M2/M3): 这是 Apple Silicon 过渡期常见的问题。某些 Pods 可能不支持当前的架构，或者 Pods 的构建配置与项目不匹配。
      • 检查 Podfile: 查看是否有针对特定架构的特殊配置，例如 arm64。
      • 检查 Excluded Architectures: 在你的项目和所有 Target 的 Build Settings 中，检查 Excluded Architectures 是否正确设置。在 Debug 模式下，通常会将 arm64 添加到模拟器的 Excluded Architectures 中，以避免 M1 Mac 在模拟器上构建 arm64 slice 导致冲突（但实际设备构建时要去掉）。确保 Release 模式没有错误地排除了必要的架构。
      • Rosetta 模式: 有时，为了兼容旧的或未更新的 Pods，你可能需要在 Rosetta 模式下运行 Xcode。关闭 Xcode，在 Finder 中找到 Xcode 应用，右键选择“显示简介”，勾选“使用 Rosetta 打开”。但这只是一个临时解决方案，长期应确保所有依赖都支持 Apple Silicon。
      • 针对 Pods 的 Workaround: 有些 Pods 需要在 Podfile 中添加特定的 post_install 脚本来处理架构问题。例如：
        ruby
        post_install do |installer|
        installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
        config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
        end
        end
        end
    • 检查 Podfile.lock 和 Manifest.lock: [CP] Check Pods Manifest.lock 脚本会验证 .xcconfig 文件中的校验和是否与 Podfile.lock 匹配。如果不匹配，说明你在运行 pod install 后修改了某些设置而没有重新运行，或者缓存问题。运行 pod install 通常能解决。
  • Carthage:
    • carthage update/build 是否运行? 确保你在正确的分支和目录下运行了 carthage update --use-xcframeworks 或 carthage build。
    • Build Phases 配置: 检查你的项目 Target 的 Build Phases 中，用于拷贝 Carthage Frameworks 的 Run Script 阶段是否配置正确，包括输入文件 (Input Files) 和输出文件 (Output Files)。
    • 架构问题: 类似 Pods，确保 Carthage 构建的 Frameworks 支持目标架构，或者在使用 Rosetta。尝试使用 carthage build --no-use-binaries 强制本地重新构建 Frameworks。
  • Swift Package Manager (SPM):
    • SPM 的集成错误通常不会直接导致 PhaseScriptExecution 失败，因为它主要在构建之前解析依赖。但如果 SPM 包包含构建工具或生成的文件被后续的 Run Script 使用，那些脚本可能会失败。
    • 尝试 File -> Packages -> Resolve Package Versions 或 Update to Latest Package Versions。
    • 清理 SPM 缓存：File -> Packages -> Clean Package Caches。

7. 检查自定义构建脚本

如果失败的脚本是你自己添加的 Run Script 阶段：

  • 定位脚本内容: 在你的项目 Target 的 Build Phases 中找到该 Run Script 阶段。双击它可以查看脚本内容。
  • 仔细检查脚本: 阅读脚本代码，查找可能的错误：
    • 语法错误？（虽然 shell 脚本语法比较宽松，但也可能出错）
    • 使用了不存在的命令？（见步骤 4, 5）
    • 访问了错误的文件路径？（使用 echo 打印路径进行调试）
    • 逻辑错误？例如，脚本可能期望某个文件存在，但它不存在；或者脚本的判断条件有问题。
    • 命令执行失败？（例如，一个 cp 命令失败了，或者一个外部工具返回了错误）
  • 手动在终端中运行脚本: 这是一个强大的调试技巧。
    • 复制 Build Phases 中的脚本内容。
    • 打开终端。
    • 进入你的项目根目录（或脚本期望运行的目录）。
    • 模拟 Xcode 环境: 尽量模拟 Xcode 的构建环境。许多构建变量 (如 $SRCROOT, $BUILT_PRODUCTS_DIR) 在终端中是未定义的。你需要手动定义它们，或者将脚本中使用了这些变量的部分替换为实际的路径。
    • 将脚本内容粘贴到终端中执行。观察输出信息，这通常会比 Xcode 的构建日志更详细，能帮你 pinpoint 错误发生在哪一行。
    • 调试技巧: 在脚本的关键位置添加 echo "Debug: Variable value is $VARIABLE" 来打印变量值。使用 set -e 在脚本开头，这样一旦有命令返回非零退出码，脚本就会立即停止，这有助于找到第一个失败的命令。

8. 架构兼容性问题 (特别是 Apple Silicon / M1/M2/M3)

这是一个在 M1 芯片发布后变得非常突出的问题。有些旧的脚本、第三方库或工具可能只支持 x86_64 (Intel) 架构，而在 arm64 (Apple Silicon) 架构下运行会出错。

  • 检查错误日志: 错误日志中可能会包含关于架构的提示，例如尝试加载 x86_64 的库失败等。
  • 确认依赖的架构: 检查你的 Pods, Carthage Frameworks 或其他二进制依赖是否提供 arm64 切片 (slice)。
  • Build Settings:
    • 检查项目和 Target 的 Architectures (ARCHS) 设置。通常设置为 Standard Architectures 即可。
    • 检查 Excluded Architectures (EXCLUDED_ARCHS)。如前所述，模拟器在 Debug 模式下可能需要排除 arm64。
    • 检查 Build Active Architecture Only (ONLY_ACTIVE_ARCH). 在 Debug 模式下通常设置为 Yes (YES)，只构建当前设备的架构，加快编译速度。在 Release 模式下通常设置为 No (NO)，构建所有支持的架构。确保这些设置符合你的预期。
  • 使用 arch -x86_64 运行脚本: 如果某个脚本（例如 CocoaPods 或 Carthage 的脚本，或者依赖特定 Intel 工具的自定义脚本）必须在 Intel 架构下运行，可以在 Run Script 阶段的脚本内容前加上 arch -x86_64，强制脚本及由它调用的命令在 Rosetta 模拟的 Intel 环境下执行。
    bash
    arch -x86_64 /bin/sh -c "[脚本内容]"
    或者直接在脚本开头添加：
    bash
    #!/bin/sh
    arch -x86_64 "$@ /bin/sh"
    exit $? # 确保子进程的退出码被传递
    这通常用于 Pods 或 Carthage 的主脚本，或者直接在 Run Script 阶段的 shell 文本框中整个脚本内容前加上 arch -x86_64（如果脚本是通过路径引用的）。注意： 这种方法依赖于安装了 Rosetta。这是权宜之计，最好还是更新依赖或脚本以原生支持 arm64。

9. 考虑外部工具或依赖

如果脚本调用了 swiftlint, rswift, nodemon, python 等外部工具，请检查：

  • 工具是否已安装?
  • 工具版本是否正确? 有时特定版本的工具与你的代码或构建环境不兼容。
  • 工具是否在 PATH 中? (见步骤 5)
  • 工具本身是否有错误? 手动在终端中运行该工具，看看它是否能正常工作。

10. 清理 Derived Data

清理构建目录 (Clean Build Folder) 更加彻底的一种方式是清理 Derived Data 目录。这个目录包含了所有中间构建文件、索引、日志等。损坏的 Derived Data 可能会导致各种奇怪的构建问题。

  • 在 Xcode 菜单栏选择 File -> Project Settings... (或 Workspace Settings...)。
  • 点击 Derived Data 旁边的灰色箭头，这会在 Finder 中打开 Derived Data 目录。
  • 关闭 Xcode。
  • 删除该目录下的对应项目或工作空间的文件夹。（或者直接删除整个 DerivedData 目录，但这会清除所有项目的缓存，需要重新索引）。
  • 重新打开 Xcode 并尝试构建。

注意: 清理 Derived Data 会导致 Xcode 重新索引项目，第一次构建可能会比较慢。

11. 重启 Xcode 和你的电脑

这听起来像是万能的废话，但在软件开发中，重启确实能解决一些临时的、难以解释的环境问题。尝试先重启 Xcode，如果问题依旧，再重启电脑。

12. 检查 Xcode 版本和项目设置

  • 确保你使用的 Xcode 版本与项目要求的版本兼容。
  • 如果项目是从旧版本迁移过来的，检查项目和 Target 的 Build Settings，确认没有过时的或冲突的设置。
  • 尝试切换到较旧或较新的 Xcode 版本（如果你安装了多个）。

13. 寻求社区帮助

如果以上步骤都无法解决问题，是时候寻求外部帮助了。

  • 详细描述问题: 在论坛或社区（如 Stack Overflow, Apple Developer Forums）提问时，提供尽可能多的信息：
    • 完整的错误信息。
    • 构建日志中的详细输出 (这是最重要的！)。
    • 你已经尝试过的故障排除步骤。
    • 你的 Xcode 版本、macOS 版本、项目使用的第三方库 (CocoaPods, Carthage, SPM) 及其版本。
    • 问题发生前的操作 (例如，添加了新的库、修改了构建设置、更新了 Xcode 等)。
  • 搜索: 在搜索引擎中搜索完整的错误信息，尤其是日志中最具体的错误行。很有可能别人也遇到过同样的问题并找到了解决方案。

5. 预防措施：如何减少此类错误的发生

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

  • 理解构建阶段: 花时间了解你的项目有哪些构建阶段，特别是 Run Script 阶段，以及它们的作用。
  • 审查第三方库脚本: 如果引入新的第三方库，特别是通过 Pods 或 Carthage，了解它们添加了哪些构建脚本，以及这些脚本的功能。
  • 保持工具和依赖更新: 确保你的 Xcode、CocoaPods、Carthage 以及其他构建工具和依赖库保持更新，以获得最新的 Bug 修复和架构支持。
  • 谨慎修改构建设置: 随意修改 Build Settings 可能会导致难以追踪的问题。在修改前了解设置的作用。
  • 版本控制: 将你的项目代码、Podfile, Podfile.lock, Cartfile, Cartfile.resolved 等文件都纳入版本控制，方便回溯到没有问题的状态。
  • 编写健壮的自定义脚本:
    • 使用 set -e 使脚本在任何命令失败时立即退出。
    • 使用 echo 或其他日志记录方式在脚本中输出信息，方便调试。
    • 使用 which 或路径检查来确保脚本依赖的外部工具或文件存在。
    • 明确处理脚本中的路径，尽量使用 Xcode 提供的构建变量。

6. 总结

Command PhaseScriptExecution failed with a nonzero exit code 错误是 Xcode 开发中一个常见但可解决的问题。解决它的关键不在于盲目尝试各种方法，而在于 理解错误发生的本质——一个 shell 脚本执行失败了，以及 系统性地分析日志——日志是诊断问题的金钥匙。

遵循本文提供的步骤，从检查日志开始，逐步排查文件权限、路径、环境变量、第三方库配置、自定义脚本、架构兼容性等常见原因，绝大多数情况下你都能够找到并解决问题。记住，耐心和细致是克服这类错误的最有力武器。

祝你构建顺利！

发表评论

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

滚动至顶部