當App Builder建置失敗時：讀取日誌，找出原因，重新建置

App Builder 應用程式會依照配方，一個接一個建置程式，其中任何一個都可能失敗。本指南追蹤測試 NAS 上的一次真實失敗：包含 70 個配方的應用程式 TurboShell，在第七個配方 Korn shell ksh93 停了下來。

哪裡失敗的配方
日誌最後幾行
原因錯誤訊息指出什麼
修改修正配方或應用程式
重試沿用已完成的配方

截圖來自修正前後的 Bucket & Code Server IDE 1.0.0-49。

01失敗的地方

建置失敗時，應用程式會維持原狀。如果先前有成功的建置，啟用、下載和 匯出為 QPKG 仍會使用那次建置。側邊欄將最近一次建置標示為失敗，應用程式頁面的流程也會顯示這次失敗。

建置順序 卡片指出失敗的配方與階段。在這個例子中，它前面的每個配方都顯示通過；它後面的配方顯示 未執行到，並保留先前建置的日誌。

「建置順序」卡片：上次建置失敗，訊息為 builder: FAILED ksh93 in build (exit 1)；配方 1 到 6 通過，ksh93 在編譯時失敗，fish 未執行到，附有「先前的記錄」

02閱讀配方日誌

按配方那一列的記錄，會開啟建置器為這個配方寫下的內容：各個階段、編譯器的輸出、稽核與檢查。原因就在日誌末尾附近。

ksh93 的日誌：libast/misc/magic.c 顯示「unknown type name Magic_t; did you mean magic_t」；接著 mamake 建立 magic.o 時以代碼 1 結束，套件建置回報 make 失敗

建置工作本身的日誌在底部面板（Ctrl+J）的工作下，結尾是同樣幾行：建置器會把配方日誌的最後 40 行複製進去。
失敗配方的建置樹會留在應用程式的建置資料夾中，直到應用程式下一次建置為止，位置是資料目錄中的 apps/<app>/build/work/<recipe>。在編輯器的終端機中進入這個資料夾，就能查看原始碼和產生的檔案。

03找出原因

編譯器要找的是 ksh 自己的型別 Magic_t，卻建議改用 magic_t，也就是 libmagic 的型別；libmagic 是 file 指令的函式庫。所以 ksh 原始碼中的 #include <magic.h> 找到的是 libmagic 的標頭檔，而不是 ksh 自己的。

TurboShell 也會建置 file 配方，將 libmagic 的 magic.h 安裝到應用程式前綴。每個配方的搜尋路徑都包含該前綴的 include 目錄，讓程式找到先前建置的函式庫。TurboShell 首次建置時先建置 ksh93、後建置 file，因此成功。之後的建置從上次成功版本的副本開始；副本的前綴已有 libmagic 標頭，ksh93 因而誤用了它。

當錯誤訊息指出某個名稱時（就像這次），請沿著原始碼、先前的配方和建置環境追查這個名稱。日誌會告訴您這次建置停在哪裡，但不會告訴您哪項變更能修好它。

04您可以更改的內容

修正後的配方。 在兩次套件發行之間，配方會以已簽署目錄的形式送到 NAS。應用程式 頁面上的 配方庫 卡片會顯示建置使用的配方來源和上次檢查時間；檢查配方更新 可立即檢查。這次修正後的 ksh93 配方隨目錄 2026.10.08-1 送達，它讓 ksh93 不再讀取前綴中的標頭檔。
應用程式。 在應用程式頁面按變更，可新增或移除配方，並設定建置環境與連結方式。與其他配方衝突的程式可改放到獨立的應用程式中。
環境。 如果配方需要較新的編譯器，或需要環境中沒有的建置工具，請用變更選擇另一個環境。

05自行變更配方的來源

如果修正後的配方還沒送達，或程式已經有比配方庫配方更新的發行版，可以複製一份配方，在副本中指定新的來源。副本放在您任一專案的 recipes/ 資料夾中；採用該專案配方的應用程式會建置這份副本，而不是配方庫的配方。配方庫與其他應用程式維持不變。在 Bucket & Code Server IDE 1.0.0-55 的配方庫中，tmux 配方建置 3.7c；此處的副本建置 3.8。

建置作業的日誌會在 recipe library: 這一行列出使用中的配方庫。套件本身的配方庫位於 /usr/bin/bucketvs/share/bucketvs/recipes/；目錄的配方庫位於資料目錄中的 recipes/current/library/。在編輯器的終端機中、於專案資料夾內，從該處複製配方資料夾，並計算新封存檔的 sha256：

mkdir -p recipes
cp -r /usr/bin/bucketvs/share/bucketvs/recipes/tmux recipes/
curl -fsSL https://github.com/tmux/tmux/releases/download/3.8/tmux-3.8.tar.gz | sha256sum
e79c699c7e949dccd0a4a125e17b8d1261e311b16979dbc8eb34542f3966d82e  -

在 recipes/tmux/recipe.json 中有三個值要改：版本、位址和 sha256。

"version": "3.8",
"source": {
  "url": "https://github.com/tmux/tmux/releases/download/3.8/tmux-3.8.tar.gz",
  "sha256": "e79c699c7e949dccd0a4a125e17b8d1261e311b16979dbc8eb34542f3966d82e"
},

儲存檔案時會檢查專案的配方，並在編輯器的問題檢視中列出結果；bvs recipe lint . 會在終端機中執行相同的檢查。專案檢視的配方卡片會將副本標示為 取代配方庫的 3.7c。有問題的副本會被排除，配方庫的配方也不會代替它：需要 tmux 的建置會在開始前停止並說明原因。
只要有專案含有配方，應用程式頁面的變更就會顯示 專案的配方。選擇專案，按 儲存變更，再按 重新建置。建置作業的日誌會列出從專案讀取的配方，並寫出 tmux replaces the library's tmux 3.7c in this app。
建置方式相同的發行版只需要改這三個值。若需要其他 configure 選項或修補程式，也要修改 build.sh；您的第一個自訂配方會說明這個檔案。
副本依名稱取代配方庫的配方，與版本無關。即使配方庫的配方版本超過副本，應用程式仍會建置副本：請將 專案的配方 改回 無：僅配方庫，或刪除副本。

06重新建置

在應用程式頁面按 重新建置 會啟動新的建置作業。如果應用程式的檔案在失敗之後沒有變動，建置會從失敗的地方接著做：失敗那次已完成的配方會重複使用，失敗的配方則重新建置，這裡就是用目錄中修正版配方建置的 ksh93。

07當建置通過但程式未啟動時

每次建置在取代應用程式之前都會檢查結果：每個配方自己的檢查，以及一項分析，它會讀取每個程式和函式庫，但不執行它們。應用程式的 相依性 分頁會列出分析的發現：缺少的函式庫、函式庫沒有定義的版本、指向應用程式外部的 RUNPATH，或是需要比應用程式目標更新 glibc 的程式。對於支援的發現，面板會提供建議的處理方式，通常是一個按鈕：加入 … 並建置、切換為…並建置、修補 RUNPATH、選擇其他環境 或 只為這台 NAS 建置。在 NAS 上，bvs deps <app> 會印出同樣的清單。