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。

這個錯誤訊息看起來像是 Xcode 本身出了問題，但實際上，它通常指向的是您專案中「腳本階段 (Run Script Phase)」執行失敗。理解這個錯誤的根本原因，以及如何系統性地排查，對於提高開發效率至關重要。

本文將深入解析這個錯誤，從它在 Xcode 編譯流程中的位置，到錯誤訊息的組成，再到各種可能的根源及詳細的解決方案，幫助您徹底征服這個惱人的問題。

什麼是 Xcode 的「編譯階段」與「腳本階段 (Phase Script Execution)」？

在深入探討錯誤之前，讓我們先理解 Xcode 的編譯過程。一個典型的 Xcode 專案編譯（Build）並非單一操作，而是一個由多個「階段 (Phases)」組成的流程。這些階段按照特定的順序執行，完成從原始碼編譯到最終產品（例如 .app 文件）生成的各項任務。常見的編譯階段包括：

Process Sources: 編譯您的原始碼文件（Swift, Objective-C）。
Compile Assets: 編譯資產文件（圖片、音訊等）。
Link Binary With Libraries: 將編譯好的目標文件與所需的庫文件鏈接起來。
Copy Files: 複製文件到產品包中。
Compile Asset Catalogs: 編譯 Asset Catalogs。
Run Script Phase (腳本階段): 執行開發者自定義的 shell 腳本。
Code Signing: 對最終產品進行代碼簽署。

Phase Script Execution 就是上述列表中的第六項。它允許開發者在標準的編譯流程中插入自定義的自動化任務。這些腳本可以執行非常多樣化的操作，例如：

整合第三方依賴管理器: CocoaPods 或 Carthage 在編譯過程中嵌入框架或處理資源。
運行靜態分析工具: SwiftLint, OCLint 等檢查代碼風格或潛在問題。
處理資源文件: 壓縮圖片、加密文件、生成本地化字串表。
生成代碼: 基於協議文件生成網路請求代碼、Core Data 模型代碼等。
版本控制操作: 根據 Git Commit 信息生成版本號。
其他自定義自動化任務。

正是這些靈活多變的腳本，為開發流程帶來了極大的便利，但也埋下了 command phasescriptexecution failed with a nonzero exit code 錯誤的伏筆。當這些腳本中的任何一個在執行過程中出錯時，就會觸發這個錯誤，並導致整個編譯過程停止。

剖析錯誤訊息：`command phasescriptexecution failed with a nonzero exit code`

現在，讓我們來拆解這串錯誤訊息：

command: 指的是 Xcode 試圖執行的一個指令。在 Phase Script Execution 的上下文中，這個指令就是您在腳本階段配置的那個 shell 腳本，或者腳本中調用的其他命令。
phasescriptexecution: 明確指出這個錯誤發生在「腳本階段」。這是一個重要的線索，它告訴您問題不在於原始碼編譯、鏈接或資產處理等其他標準階段，而是出現在您添加的或第三方庫添加的腳本裡。
failed: 表示這個指令未能成功完成。
with a nonzero exit code: 這是最關鍵的部分。在 Unix/Linux/macOS 系統中，程式或腳本執行完畢後，會返回一個「退出碼 (exit code)」。
- 退出碼為 0 (zero exit code) 通常表示程式或腳本執行成功，沒有遇到任何錯誤。
- 退出碼為非零 (nonzero exit code) 則表示程式或腳本在執行過程中發生了錯誤。不同的非零值可能代表不同類型的錯誤，但對 Xcode 來說，只要不是 0，就一律視為失敗。

綜合起來，command phasescriptexecution failed with a nonzero exit code 這個錯誤訊息的含義就是：在 Xcode 的編譯過程的腳本階段，一個被執行的腳本（或腳本中的命令）在執行過程中發生了錯誤，並返回了一個非零的退出碼，導致整個腳本階段執行失敗。

這個錯誤訊息本身並不直接告訴您 為什麼 腳本失敗了，它只是一個結果的宣告。真正的錯誤原因藏在腳本自身的輸出中，而這些輸出會顯示在 Xcode 的「編譯日誌 (Build Log)」裡。

診斷問題的關鍵：閱讀 Xcode 的編譯日誌 (Build Log)

正如前面所說，command phasescriptexecution failed with a nonzero exit code 只是錯誤的表象。要找到根源，您必須學會深入挖掘 Xcode 的編譯日誌。

當編譯失敗時，Xcode 會在「問題導航器 (Issue Navigator)」中顯示這個錯誤。點擊這個錯誤，通常會導航到「報告導航器 (Report Navigator)」中的相應編譯記錄。

在「報告導航器」中，找到最近一次失敗的編譯記錄，展開它，然後找到 Run Script 或 PhaseScriptExecution 相關的條目。展開這個條目，您會看到腳本的執行命令以及它的標準輸出 (stdout) 和標準錯誤輸出 (stderr)。

重點來了： 在這個展開的區域裡，通常會在錯誤訊息 command phasescriptexecution failed with a nonzero exit code 之前或緊隨其後，顯示腳本本身輸出的錯誤信息。 這些信息可能是一個文件找不到、一個命令不存在、腳本語法錯誤、外部工具報告的錯誤等等。這才是定位問題的真正線索！

例如，您可能會看到這樣的日誌片段：

“`
… (之前的編譯步驟)
PhaseScriptExecution [Your Script Phase Name] Build/Intermediates.noindex/YourApp.build/Debug-iphonesimulator/YourApp.build/Script-XXXXXXXX.sh
cd /Users/yourname/YourProject
export SCRIPT_INPUT_FILE_COUNT=0
export SCRIPT_OUTPUT_FILE_COUNT=0
/bin/sh -c /Users/yourname/YourProject/Build/Intermediates.noindex/YourApp.build/Debug-iphonesimulator/YourApp.build/Script-XXXXXXXX.sh

The command line is… (執行的腳本命令)

/bin/sh: ./some_script.sh: Permission denied <– 腳本執行時輸出的錯誤！
or

SwiftLint must be installed. Use brew install swiftlint. <– 外部工具的錯誤！
or
/Users/yourname/YourProject/Scripts/my_script.sh: line 5: unexpected end of file <– 腳本語法錯誤！

Command PhaseScriptExecution failed with a nonzero exit code <– 最終的錯誤報告
… (之後的編譯步驟被跳過)
“`

請務必仔細閱讀在 Command PhaseScriptExecution failed... 這一行之前的所有輸出。 這通常包含了解決問題所需的具體信息。

常見導致 `command phasescriptexecution failed with a nonzero exit code` 的原因及解決方案

既然我們知道錯誤是腳本執行失敗引起的，並且知道如何從日誌中查找具體原因，接下來我們將列出一些最常見的導致腳本階段失敗的原因，並提供詳細的解決方案。

1. 權限問題 (Permission Issues)

這是非常常見的原因。Xcode 執行腳本時，可能因為腳本文件本身沒有執行權限而失敗。

日誌中的線索: 通常會看到類似 Permission denied 的錯誤訊息。
原因:
- 腳本文件 (.sh 或其他類型) 沒有可執行權限。
- 腳本嘗試寫入 Xcode 沒有權限訪問的目錄。
解決方案:
- 檢查腳本文件權限:
  - 打開終端機 (Terminal)。
  - 使用 cd 命令進入到您的專案目錄或腳本文件所在的目錄。
  - 使用 ls -l your_script_name.sh 查看文件權限。如果權限像 -rw-r--r-- 這樣沒有 x，就表示沒有執行權限。
  - 使用 chmod +x your_script_name.sh 命令為腳本文件添加執行權限。
  - 如果您使用的是版本控制（如 Git），請確保腳本文件在版本控制中被標記為可執行。
- 檢查目標目錄權限: 如果腳本需要寫入文件或目錄，請確保 Xcode 有權限訪問這些位置。通常編譯相關的輸出會寫入 DerivedData 目錄，這部分 Xcode 通常會處理好權限。如果寫入專案目錄下的其他位置，請檢查這些位置的權限。

2. 路徑問題 (Path Issues)

腳本中引用的文件、目錄或命令的路徑不正確，是另一個極為常見的原因。

日誌中的線索: 類似 No such file or directory, command not found 等錯誤訊息。
原因:
- 腳本中使用了相對路徑，但在 Xcode 執行腳本時，當前工作目錄 (Current Working Directory) 與您預期的不同。
- 腳本中引用的工具（如 swiftlint, pod, carthage）不在 Xcode 執行腳本時的 PATH 環境變數中。
- 路徑中包含空格或其他特殊字符，但沒有正確引用（加引號）。
解決方案:
- 使用絕對路徑或 Xcode 環境變數:
  - 盡量避免使用硬編碼的相對路徑。
  - 利用 Xcode 提供的環境變數，例如：
    - ${SRCROOT}: 專案根目錄 (Project Root)
    - ${PODS_ROOT}: CocoaPods 的根目錄
    - ${BUILD_DIR}: 編譯輸出目錄
    - ${DERIVED_FILE_DIR}: 生成文件目錄
    - … 還有許多其他變數，可以在 Xcode 的 Build Settings 中查看。
  - 例如，如果您的腳本在專案根目錄下的 Scripts 文件夾裡，並引用了同一個文件夾裡的另一個文件，可以使用 ${SRCROOT}/Scripts/your_other_file.txt。
- 確保工具在 PATH 中:
  - Xcode 執行腳本時的環境 PATH 可能與您在終端機中設置的不同。
  - 如果您使用 Homebrew 安裝了工具（如 SwiftLint），它們通常安裝在 /usr/local/bin 或 /opt/homebrew/bin。您可以嘗試在腳本的開頭添加以下行來擴展 PATH：
    shell export PATH="$PATH:/usr/local/bin:/opt/homebrew/bin"
  - 或者，使用工具的完整絕對路徑來執行它，例如 /opt/homebrew/bin/swiftlint。
  - 在終端機中使用 which your_tool_name 命令可以找到工具的絕對路徑。
- 正確引用包含空格的路徑: 如果路徑或文件名中包含空格，請使用雙引號將其括起來，例如 "/path/to/my folder/my script.sh".

3. 腳本語法錯誤 (Script Syntax Errors)

腳本本身的語法有誤，導致 shell 無法正確解析和執行。

日誌中的線索: Shell 解釋器（如 /bin/sh 或 /bin/bash）會報告語法錯誤，例如 unexpected end of file, syntax error, command not found (如果命令名稱拼寫錯誤) 等。錯誤訊息通常會包含發生錯誤的行號。
原因:
- Typo (打字錯誤)。
- 引號不匹配。
- 使用了未定義的變數。
- 條件判斷或循環語法錯誤。
- 使用了在目標 shell (/bin/sh 通常是 /bin/bash 的簡化版或 /bin/zsh 的兼容模式) 中不受支持的語法。
解決方案:
- 仔細檢查日誌中的錯誤信息和行號: 錯誤訊息通常會精確指出哪個文件哪一行出了問題。
- 在終端機中測試腳本: 將腳本的內容直接複製到終端機中執行，看看是否會報錯。或者，嘗試以 Xcode 執行腳本時的環境來模擬執行：
  - 在 Run Script Phase 中添加 echo "Current directory: $(pwd)" 和 echo "PATH: $PATH" 來了解執行環境。
  - 在 Run Script Phase 的頂部添加 set -e。這條命令會使得腳本在遇到任何錯誤時立即退出，而不會繼續執行下去，這有助於更快地定位第一個錯誤發生點。
  - 添加 set -x。這條命令會在執行每一行命令之前將其打印出來，這對於追蹤腳本執行流程和變數值非常有幫助（調試完後記得移除）。
- 使用 Shell 語法檢查工具: 有一些工具可以幫助檢查 shell 腳本的語法錯誤，例如 shellcheck。

4. 環境變數差異 (Environment Variable Differences)

Xcode 提供的編譯環境與您在終端機中的交互式環境不同，這可能導致依賴於特定環境變數或配置的腳本失敗。

日誌中的線索: 腳本中的命令無法找到所需的文件或配置，因為相關的環境變數（如 PATH, 特定工具的配置路徑等）未設置或設置不正確。
原因:
- PATH 變數不同（已在路徑問題中討論）。
- 腳本依賴於用戶級別的環境變數（如設置在 ~/.bash_profile, ~/.zshrc 中的）而 Xcode 的編譯環境不會自動加載這些文件。
- Xcode 的 Build Settings 中設置的變數未被腳本正確使用。
解決方案:
- 在腳本中明確設置所需的環境變數: 如果腳本依賴於特定的環境變數，直接在腳本的開頭使用 export VAR_NAME=value 來設置它。
- 從 Xcode 的 Build Settings 中獲取變數: Xcode 會將許多 Build Settings 作為環境變數暴露給腳本。使用 ${VARIABLE_NAME} 語法來引用它們。確保您在腳本設置中勾選了 “Pass build settings in environment”。
- 對於依賴用戶配置的工具: 有些工具（如 Fastlane）可能需要訪問用戶的某些配置或認證信息。這在 Xcode 的編譯環境中可能會受到限制。考慮這些工具是否適合在編譯階段運行，或者是否需要在 CI/CD 環境中處理這些問題。

5. 外部工具或依賴管理器問題 (External Tools / Dependency Manager Issues)

很多腳本階段的失敗是由於腳本調用的外部工具或依賴管理器本身執行出錯。例如，CocoaPods, Carthage, SwiftLint, Fastlane 等。

日誌中的線索: 腳本輸出會包含外部工具或依賴管理器的錯誤信息。例如，CocoaPods 可能會報告找不到 Podfile，SwiftLint 可能會報告配置文件錯誤，Carthage 可能會報告編譯框架失敗等。
原因:
- 外部工具未安裝或版本不對。
- 外部工具的配置文件有錯誤（例如 SwiftLint 的 .swiftlint.yml 語法錯誤）。
- 依賴管理器（如 CocoaPods）的配置文件 (Podfile) 有錯誤，或者在運行編譯之前沒有執行 pod install。
- 外部工具本身存在 bug 或與當前 Xcode 版本不兼容。
- 網絡問題（如果工具需要下載依賴）。
解決方案:
- 仔細閱讀日誌中外部工具輸出的信息: 這是最重要的線索。錯誤信息通常會提示具體的工具和問題。
- 確認外部工具已安裝且版本正確: 使用 which tool_name 和 tool_name --version 在終端機中檢查。如果是在 CI/CD 環境中，確認環境中已安裝這些工具。
- 對於 CocoaPods/Carthage:
  - 確認您在專案根目錄下運行了 pod install 或 carthage update/bootstrap。
  - 檢查 Podfile/Cartfile 中是否有語法錯誤或依賴衝突。
  - 刪除 Pods 文件夾、Podfile.lock 文件、DerivedData 目錄，然後重新運行 pod install。
  - 對於 Carthage，刪除 Carthage 文件夾，然後重新運行命令。
- 對於 SwiftLint:
  - 檢查 .swiftlint.yml 配置文件是否存在且語法正確。
  - 確認 SwiftLint 工具本身在 PATH 中或使用其絕對路徑。
  - 嘗試在終端機中手動運行 SwiftLint 命令，看看是否能複現錯誤。
- 隔離外部工具: 如果懷疑是外部工具問題，可以暫時禁用相關的 Run Script Phase，或者在終端機中獨立運行腳本中調用的外部工具命令，以便更清晰地看到其錯誤輸出。

6. Xcode 的 Cache 或 DerivedData 問題

有時，Xcode 的臨時文件或緩存可能損壞，導致編譯過程中出現奇怪的錯誤，包括腳本階段失敗。

日誌中的線索: 錯誤訊息可能不明確，或者在您確認腳本和路徑都正確的情況下仍然出現。
原因: Xcode 的編譯緩存、索引或中間構建文件損壞。
解決方案:
- Clean Build Folder: 在 Xcode 菜單欄選擇 Product > Clean Build Folder (或使用快捷鍵 Shift + Command + K)。這會清理當前 Build 配置的輸出文件。
- 刪除 DerivedData 目錄: DerivedData 目錄包含 Xcode 生成的索引、模塊緩存、編譯中間文件等。完全刪除它可以解決許多編譯問題。
  - 在 Xcode 菜單欄選擇 File > Project Settings 或 Workspace Settings。
  - 點擊 Derived Data 旁邊的箭頭圖標，會打開 Finder 顯示該目錄。
  - 退出 Xcode。
  - 在 Finder 中將 DerivedData 文件夾移到垃圾桶並清空。
  - 重新打開 Xcode 並嘗試編譯。

7. 專案配置問題 (Project Configuration Issues)

Run Script Phase 本身的配置可能有誤。

日誌中的線索: 錯誤可能不明確，或者看起來像是腳本沒有按預期執行。
原因:
- 腳本的 shell 類型配置不正確（例如腳本是 bash 語法，但配置使用了 sh 或 zsh）。
- 腳本的輸入/輸出文件配置有誤，導致 Xcode 的依賴分析出錯（儘管這通常表現為其他類型的編譯警告或錯誤，但也可能間接導致腳本失敗）。
- 腳本設置為在錯誤發生時不停止編譯，但後續步驟因此失敗。
- 腳本被設置為僅在特定 Build Configuration (如 Debug) 或特定架構下運行，但在不應運行的情況下卻被觸發或配置錯誤。
解決方案:
- 檢查 Run Script Phase 配置:
  - 進入專案的 Build Phases 設置頁面。
  - 找到導致錯誤的 Run Script Phase。
  - 檢查頂部的 shell 配置（默認是 /bin/sh，通常夠用，但如果腳本使用了特定的 bash 或 zsh 語法，可能需要更改）。
  - 查看腳本內容本身是否正確。
  - 檢查 “Show environment variables in build log” 和 “Show shell script in build log” 選項（有助於調試）。
  - 檢查 “Run script only when installing” 或其他條件設置是否符合預期。
- 檢查 Input/Output Files (高級): 對於複雜的腳本，正確配置輸入/輸出文件有助於 Xcode 進行更精確的增量編譯判斷。如果配置錯誤，可能導致腳本在不必要的時機運行或因文件依賴問題而失敗。大多數簡單腳本不需要配置這些。

8. 代碼簽署問題 (Code Signing Issues)

雖然不直接，但如果腳本階段涉及處理或打包可執行文件或框架，並且這些文件在後續的代碼簽署階段出現問題，有時錯誤會回溯到腳本階段報告。

日誌中的線索: 錯誤信息可能間接提及簽名相關的問題，或者在腳本成功執行後，後續的簽名步驟失敗。
原因:
- 腳本生成的輸出文件或嵌入的框架不符合代碼簽署的要求。
- 簽名證書或配置文件有問題。
解決方案:
- 確保您的代碼簽署設置在專案的 Build Settings 中是正確的。
- 如果您在腳本中處理框架或可執行文件，確保它們在腳本處理後是完整且未被破壞的，以便後續的簽名步驟能夠成功。
- 檢查鑰匙串訪問 (Keychain Access) 中是否有過期的或衝突的證書。

9. 模擬器或設備問題 (Simulator/Device Issues)

極少數情況下，如果您在腳本中與特定的模擬器或設備環境交互（例如，運行一個需要在模擬器上安裝的測試應用），模擬器的狀態問題可能導致腳本失敗。

日誌中的線索: 錯誤訊息可能提及與目標設備或模擬器相關的信息。
原因: 模擬器狀態異常、需要更新或重置。
解決方案:
- 重啟相關的模擬器。
- 從 Xcode 菜單選擇 Window > Devices and Simulators，右鍵點擊有問題的模擬器，選擇 Erase Content and Settings...。
- 確保您的 Xcode 和模擬器是最新版本。

系統性的故障排除流程

面對 command phasescriptexecution failed with a nonzero exit code 錯誤，採用系統性的方法至關重要。以下是一個推薦的排查流程：

保持冷靜，深呼吸。 這個錯誤很常見，幾乎總是有解決方案。
徹底清理並重新編譯。 先嘗試最簡單的解決方案：Product > Clean Build Folder，然後再次編譯。如果還是失敗，退出 Xcode，刪除 DerivedData 目錄，再重新打開 Xcode 編譯。這能排除許多緩存和臨時文件問題。
仔細閱讀編譯日誌。 這是最重要的步驟！展開失敗的 Run Script Phase 條目，逐行閱讀腳本的輸出。尋找在 Command PhaseScriptExecution failed... 之前的具體錯誤信息。錯誤信息通常會直接或間接指出問題所在（例如 Permission denied, No such file, command not found, 外部工具的錯誤提示）。
根據日誌中的線索定位問題。
- 看到 Permission denied？ -> 檢查腳本或目標目錄的權限（使用 chmod +x）。
- 看到 No such file or directory 或 command not found？ -> 檢查腳本中引用的路徑是否正確，工具是否在 PATH 中，文件是否存在。使用 ${SRCROOT} 等變數，或使用絕對路徑。
- 看到腳本中的特定行號報錯？ -> 檢查那一行及其周圍的腳本語法。在腳本開頭添加 set -e 和 set -x 來幫助調試。
- 看到外部工具（如 CocoaPods, SwiftLint）的錯誤信息？ -> 根據該工具的錯誤提示進行排查（例如運行 pod install, 檢查配置文件等）。
- 錯誤信息不明顯？ -> 嘗試在腳本中添加 echo "Executing step X..." 或 echo "VAR_NAME is $VAR_NAME" 來追蹤腳本執行進度並檢查變數值。
隔離並測試腳本。 如果腳本很複雜，嘗試將腳本內容複製出來，在終端機中手動執行。嘗試模擬 Xcode 的環境（cd 到專案目錄，手動設置相關環境變數，然後執行腳本）。這可以幫助排除是 Xcode 環境問題還是腳本本身問題。
檢查專案配置。 確認 Run Script Phase 的設置（shell 類型、Input/Output Files、條件等）是否正確。
回顧最近的更改。 這個錯誤是在您做了什麼修改後才開始出現的？回滾到之前的版本，看看問題是否消失。這對於找出引入問題的具體更改非常有幫助。常見的觸發因素包括：更新 Xcode、更新第三方庫（CocoaPods, Carthage）、修改腳本文件、修改專案文件結構、在 .gitignore 中忽略了重要文件等。
在線搜索錯誤信息。 將日誌中具體的錯誤信息（特別是外部工具輸出的錯誤）複製到搜索引擎中查找，很可能其他開發者也遇到過相同的問題並分享了解決方案。

如何預防 `command phasescriptexecution failed with a nonzero exit code` 錯誤？

雖然完全避免這個錯誤不太現實，但可以採取一些措施來降低發生的頻率：

將腳本添加到版本控制。 確保您的腳本文件 (.sh 等) 被納入版本控制，這樣團隊成員都能訪問到正確的腳本，並且可以追溯更改。
使用絕對路徑或 Xcode 環境變數。 盡量避免使用容易出錯的相對路徑。
保持外部工具和依賴管理器更新。 使用較新且與您的 Xcode 版本兼容的工具版本可以減少兼容性問題。
清晰記錄複雜的腳本和依賴。 如果您的專案使用了複雜的腳本或非標準的外部工具，請在專案文檔中清楚說明其用途和設置步驟。
在 CI/CD 環境中測試。 確保您的自動化構建流程能夠處理腳本依賴，並在 CI 環境中儘早發現問題。
使用 set -e。 在腳本開頭添加 set -e 可以讓腳本在第一個命令返回非零退出碼時就停止執行，這有助於更早發現問題。
定期清理 DerivedData。 養成定期清理 DerivedData 的習慣，可以避免一些由緩存引起的奇怪問題。

結論

command phasescriptexecution failed with a nonzero exit code 是一個 Xcode 編譯錯誤，它明確指出問題發生在 Run Script Phase。這個錯誤本身並非根本原因，而是腳本執行失敗的結果。

解決這個錯誤的關鍵在於：

理解錯誤訊息的含義。
學會仔細閱讀和分析 Xcode 編譯日誌。
根據日誌中的具體錯誤信息，系統性地排查常見原因（權限、路徑、語法、環境、外部工具、緩存、配置等）。

通過掌握這些診斷和解決技巧，您可以有效地應對這個錯誤，縮短排查時間，提高開發效率。記住，大多數時候，這個錯誤只是腳本中的一個小問題，只要找到日誌中的真正線索，解決方案就在眼前。

希望這篇文章能幫助您更深入地理解並解決 command phasescriptexecution failed with a nonzero exit code 錯誤。祝您編譯順利！

破解 Xcode 惱人錯誤：command phasescriptexecution failed with a nonzero exit code 深入解析與解決之道