儲存庫
文件
疑難排解

執行故障排除

與大多數工具一樣，了解 Turborepo 為何無法按預期運作可能會令人沮喪。此頁面涵蓋使用 turbo CLI 時的一些除錯工具，以及您可能會遇到的常見問題。

啟用詳細記錄

作為開發人員，我們擁有的最佳除錯工具就是記錄。您可以使用 --verbosity 旗標提高記錄等級。搭配 從原始碼建置，這可能是查看幕後發生情況的強大且靈活方式。

查看執行摘要

--summarize 旗標會產生並儲存關於您的 turbo run 的元資料，並將其儲存為 .turbo/runs 中的 JSON 檔案。您可以使用它來比較後續執行、檢查快取人工製品的內容，以及任務的雜湊輸入。

查看您的設定

任務設定

您可以使用最少的設定來 開始使用 Turborepo -- 這是人們喜愛 Turborepo 的原因之一！但是，當您省略設定時，Turborepo 內部會採用智慧型預設值。此外，在 monorepo 中使用 工作區設定 時，了解 Turborepo 如何詮釋您的 turbo.json 可能會令人困惑。您可以使用 --dry 或 --dry=json 來取得任何任務的「已解析」任務設定。例如

turbo run build --dry=json

在輸出中尋找 resolvedTaskConfiguration 鍵。

使用者設定

當您將儲存庫連結到 Vercel 時，Turborepo 會將設定儲存在兩個地方

  • 您的 Vercel 團隊資訊儲存在 .turbo/config.json 中。您可以檢查這個檔案，看看裡面還有什麼！
  • 驗證令牌儲存在 ~/Library/Application\ Support/turborepo/config.json 中。

檢查快取

當 turborepo 執行已設定 outputs 的任務時，它會快取這些輸出，以及該任務的記錄，位置在 node_modules/.cache/turbo/ 中。這些成品會以 tar 壓縮，但您可以解壓縮並查看它們的內容。

從原始碼建置

JavaScript 程式碼庫的其中一個優點是，你可以開啟 node_modules/ 並編輯你正在執行中的程式碼。這在 turbo 中是不可能的，因為可執行程式碼是已編譯的二進位檔，你無法內嵌編輯它。但由於程式碼庫是開放原始碼，你隨時可以取得原始碼、修改它，並在本地建置它。本文件的大部分內容都可以在 貢獻指南（在新分頁中開啟） 中找到，但即使你沒有計畫要做出貢獻，你也可以使用這些說明。

  1. 從 vercel/turbo（在新分頁中開啟） 複製 git 儲存庫
  2. cd cli
  3. 進行任何變更（例如，新增更多記錄）
  4. 執行 make
  5. 從你的專案中，使用 /:path/:to/:turbo/target/debug/turbo，而不是全域 turbo 或安裝在專案中的 turbo 版本。

常見陷阱

巢狀工作區

Turborepo 不支援巢狀工作區。因此，如果你有一個包含另一個工作區的工作區，你可能會看到意外行為。我們建議將你的工作區結構扁平化，以避免這個問題。

根部相依

如果您在單一儲存庫中定義了一個套件，而單一儲存庫中的其他多個套件使用該套件，例如標準的 ESLint 組態，您可能會想在單一儲存庫根目錄的 package.json 中宣告它，並將其列為根層依賴項。這讓您可以在整個單一儲存庫中使用依賴項，而無需在每個套件的 package.json 中宣告它。不過，這可能會導致意外的快取命中，因為 Turbo 不會在快取簽章中包含根層內部依賴項，也就是說，在單一儲存庫的 package.json（根層）中宣告的依賴項，而該依賴項在單一儲存庫內部（內部）實作。因此，如果根層內部依賴項變更，其他套件都不會重新建置。

為了解決此問題，請務必將套件的內部依賴項明確新增到其 package.json 中。您可以 在此 找到如何執行的說明。

.turbo 目錄

核心概念之一是，當宣告的輸入變更時，該任務的快取輸出會失效。在執行任何任務時，Turborepo 會建立下列目錄

  • 在儲存庫根目錄中的 .turbo
  • 如果你的專案是一個單一儲存庫（例如 apps/my-app/.turbo/），每個工作區中都會有一個 .turbo 目錄。
  • 在 node_modules/.cache 中有一個 turbo 目錄。

由於預設情況下，前兩個目錄不會被 git 忽略，因此你可能會遇到一個問題，即你兩次執行相同的任務，但會收到快取遺失的訊息，即使你沒有變更任何內容，因為產生的 .turbo 目錄會被包含為任務輸入，並使快取失效。為避免此問題，請將 .turbo 新增到你的 .gitignore 檔案中。或者，你也可以限制你的 輸入 設定，這樣 .turbo 就不會包含在快取輸入中。

常見問題

我沒有看到任何快取命中

一般來說，當你連續執行 turbo run 兩次時，你應該會在第二次執行時獲得快取命中。如果沒有發生這種情況，請再次執行這兩個建置，並使用 --summarize 標記，並將產生的執行摘要相互比較。在大多數情況下，比較應該顯示第二次執行為何沒有獲得快取命中的原因。

你也可以詢問

我看到快取命中，但我的建置中斷了

我的建置快取了錯誤的環境變數

常見的單一儲存庫問題

我的相依性未正確建置

  • 您是否在建置應用程式之前適當地打包並轉譯相依性？

    例如，tsc、tsup、esbuild、babel 和 swc 等函式庫會將較新的 JavaScript 功能轉換回「純」JavaScript。

    如果您使用 Next.js，您可能會使用 transpilePackages。請確保在 next.config.js 中加入相依性的名稱（範例（在新分頁中開啟））。

  • 您是否在相依性的 package.json 中列出 files 以指向正確的檔案？

找不到我的類型

  • 您是否在相依項的 package.json 中指定 types 或 typing 指向 .d.ts 檔案？

  • 您是否已變更或設定自訂 tsconfig.json paths？

    • 它們是否具有應用程式的正確資料夾結構？
    • 它們是否已針對 meta 架構、打包器或轉譯工具正確設定？