run

執行在 turbo.json 中指定的任務。

turbo run [tasks] [options] [-- [args passed to tasks]]

• [tasks]：Turborepo 可以同時執行一個或多個任務。若要透過 turbo 執行任務，必須在 turbo.json 中指定。
• [options]：選項用於控制 turbo run 命令的行為。可用的旗標選項如下所述。
• [-- [傳遞給任務的 args]]：您也可以將引數傳遞給底層腳本。請注意，所有引數都將傳遞給 run 命令中命名的所有任務。

如果未提供任何任務，turbo 將顯示儲存庫中套件可用的任務。

turbo run

選項

--affected

自動篩選以僅顯示受目前分支變更影響的套件。

turbo run build lint test --affected

預設情況下，此旗標等效於 --filter=...[main...HEAD]。這會從 Git 的角度考量 main 和 HEAD 之間的變更。

您可以使用各自的系統環境變數覆寫預設的 base 和 head。

# Override Git comparison base
TURBO_SCM_BASE=development turbo run build --affected
 
# Override Git comparison head
TURBO_SCM_HEAD=your-branch turbo run build --affected

--cache <選項>

預設值：local:rw,remote:rw

指定執行的快取來源。接受逗號分隔的選項清單

• local：使用本機檔案系統快取
• remote：使用遠端快取

當省略快取來源時，讀取和寫入都會停用。

快取來源使用以下值

• rw：讀取和寫入
• r：唯讀
• w：僅寫入
• 無 (local:)：不使用快取。相當於省略快取來源選項。

# Read from and write to local cache. Only read from Remote Cache.
turbo run build --cache=local:rw,remote:r
 
# Only read from local cache. Read from and write to Remote Cache.
turbo run build --cache=local:r,remote:rw
 
# Read from and write to local cache. No Remote Cache activity.
turbo run build --cache=local:rw
 
# Do not use local cache. Only read from Remote Cache.
turbo run build --cache=local:,remote:r

--cache-dir <路徑>

預設值：.turbo/cache

指定檔案系統快取目錄。

turbo run build --cache-dir="./my-cache"

也可以透過 TURBO_CACHE_DIR=example/path 系統變數設定相同的行為。

--concurrency <數字 | 百分比>

預設值：10

設定/限制任務執行的最大並行數。必須是等於或大於 1 的整數，或類似 50% 的百分比值。

• 使用 1 強制循序執行（一次一個任務）。
• 使用 100% 使用所有可用的邏輯處理器。
• 如果也傳遞了 --parallel 旗標，則會忽略此選項。

turbo run build --concurrency=50%
turbo run test --concurrency=5

--continue[=<選項>]

預設值：never

指定在發生錯誤時（例如，任務的非零結束代碼），turbo 應如何處理目前和擱置中的任務。

• 當 --continue=never 且發生錯誤時，turbo 將取消所有任務。
• 當 --continue=dependencies-successful 且發生錯誤時，turbo 將取消相依任務。相依性已成功的任務將繼續執行。
• 當 --continue=always 且發生錯誤時，turbo 將繼續執行所有任務，即使是那些相依性失敗的任務也是如此。
• 當 --continue 在未指定值的情況下指定時，它將預設為 always。

在所有情況下，turbo 都將以執行期間遇到的最高結束代碼值結束。

turbo run build --continue

--cwd <路徑>

預設值：根 turbo.json 的目錄

設定命令的工作目錄。

turbo run build --cwd=./somewhere/else/in/your/repo

--dangerously-disable-package-manager-check

Turborepo 使用您儲存庫的 lockfile 來判斷快取行為、套件圖等等。因此，我們使用packageManager 欄位來協助您穩定 Turborepo。

為了協助增量遷移或在您無法使用 packageManager 欄位的情況下，您可以使用 --dangerously-disable-package-manager-check 來選擇退出此檢查，並承擔不穩定的 lockfile 產生不可預測行為的風險。停用後，Turborepo 將盡力探索儲存庫預期的套件管理器。

--dry / --dry-run

顯示將執行的套件和任務的詳細資訊，而不是執行任務。

指定 --dry=json 以 JSON 格式取得輸出。

任務詳細資訊包含有用的資訊，例如（清單並非詳盡無遺）：

--env-mode <選項>

類型：字串

控制任務執行階段中可用的環境變數。

turbo run build --env-mode=loose

也可以透過 TURBO_ENV_MODE=strict 系統變數設定相同的行為。

strict

只有在以下鍵中指定的環境變數才可供任務使用

• env
• passThroughEnv
• globalEnv
• globalPassThroughEnv

如果指定或推斷為嚴格模式，則所有任務都以 strict 模式執行，無論其設定為何。

loose

機器上的所有環境變數都可在任務的執行階段中使用。

--filter <字串>

指定要從儲存庫圖中執行的目標。可以組合多個篩選器以選取不同的目標集。

可以組合篩選器以建立套件、目錄和 git commit 的組合。

用於篩選的微語法

• !：從選取範圍中排除目標。
• ... 使用套件：選取相對於目標之套件圖中的所有套件。在套件名稱之前使用 ... 將選取目標的相依項目，而在套件名稱之後使用 ... 將選取目標的相依性。
• ... 使用 Git commit：使用 [<from commit>]...[<to commit>] 選取範圍。
• ^：在使用 ... 時，從選取範圍中省略目標。

如需深入討論和篩選的實際使用案例，請造訪執行任務頁面。

使用任務識別碼

您也可以使用 package-name#task-name 格式，針對特定套件執行特定任務。

turbo run web#lint

進階篩選範例

您可以組合多個篩選器，以進一步精簡您的目標。多個篩選器會組合成聯集，而排除篩選器會從聯集的結果中移除套件。

# Any packages in `apps` subdirectories that have changed since the last commit
turbo run build --filter={.apps/*}[HEAD^1]
 
# Any packages in `apps` subdirectories except ./apps/admin
turbo run build --filter=./apps/* --filter=!./apps/admin
 
# Run the build task for the docs and web packages
turbo run build --filter=docs --filter=web
 
# Build everything that depends on changes in branch 'my-feature'
turbo run build --filter=...[origin/my-feature]
 
# Build everything that depends on changes between two Git SHAs
turbo run build --filter=[a1b2c3d...e4f5g6h]
 
# Build '@acme/ui' if:
# - It or any of its dependencies have changed since the previous commit
turbo run build --filter=@acme/ui...[HEAD^1]
 
# Test each package that is:
# - In the '@acme' scope
# - Or, in the 'packages' directory
# - Or, changed since the previous commit
turbo run test --filter=@acme/*{./packages/*}[HEAD^1]

--force

忽略現有的快取成品，並重新執行所有任務。

turbo run build --force

也可以透過TURBO_FORCE 環境變數設定相同的行為。

--framework-inference

預設值：true

指定是否為任務執行架構推斷。

當 false 時，自動環境變數包含會停用。

turbo run build --framework-inference=false

--global-deps <檔案 glob>

指定要雜湊的全域檔案系統相依性的 glob。適用於 .env 和根目錄中影響多個套件的檔案。

turbo run build --global-deps=".env"
turbo run build --global-deps=".env.*" --global-deps=".eslintrc" --global-deps="jest.config.ts"

--graph <檔案類型>

預設值：jpg

此命令將產生目前任務圖的 svg、png、jpg、pdf、json、html 或其他支援的輸出格式。

如果未安裝 Graphviz，或未提供任何檔案名稱，則此命令會將 dot 圖列印到 stdout。

turbo run build --graph
turbo run build test lint --graph=my-graph.svg

--log-order <選項>

預設值：auto

設定記錄輸出的順序。

預設情況下，turbo 將在 CI 環境中使用 grouped 記錄，而在其他任何地方使用 stream 記錄。當使用終端機 UI時，此旗標不適用。

turbo run build --log-order=stream

--log-prefix <選項>

預設值：auto

控制在執行任務時產生的記錄行的 <套件>:<任務>: 前置詞。

turbo run dev --log-prefix=none

--no-cache

預設值 false

不快取任務的結果。

turbo run dev --no-cache

--daemon 和 --no-daemon

turbo 可以執行背景程序來預先計算用於判斷需要完成的工作的值。此獨立程序 (daemon) 是一種最佳化，並非 turbo 正常運作的必要條件。

預設的 daemon 使用方式是使用 turbo.json 中的 daemon 欄位為您的儲存庫設定的。傳遞 --daemon 需要 turbo 使用獨立程序，而 --no-daemon 則指示 turbo 避免使用或建立獨立程序。

也可以透過 TURBO_DAEMON=true 系統變數設定相同的行為。

--output-logs <選項>

預設值：full

設定輸出記錄的類型，如果 outputLogs 在 turbo.json 中定義，則覆寫它。

turbo run build --output-logs=errors-only

--only

預設值：false

限制執行範圍僅包含指定的任務。

範例

給定此 turbo.json

{
  "$schema": "https://turbo.dev.org.tw/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"]
    }
  }
}

turbo run test --only

此命令將僅執行每個套件中的 test 任務。它不會執行 build。

此外，--only 將僅在指定的套件中執行任務，排除相依性。例如，turbo run build --filter=web --only 將僅在 web 套件中執行 build 腳本。

--parallel

預設值：false

跨套件平行執行命令，忽略任務相依性圖。

turbo run lint --parallel
turbo run dev --parallel

--preflight

僅適用於設定遠端快取時。啟用在每個快取成品和分析要求之前傳送預檢要求。後續的上傳和下載將遵循重新導向。

turbo run build --preflight

也可以透過 TURBO_PREFLIGHT=true 系統變數設定相同的行為。

--profile

以 Chrome Tracing 格式產生執行的追蹤，您可以使用它來分析效能。

您必須提供詳細程度旗標 (-v、-vv 或 -vvv) 以及 --profile 才能產生追蹤。

turbo run build --profile=profile.json -vvv

可以在像 Perfetto 這樣的工具中檢視設定檔。

--remote-cache-timeout

預設值：30

設定遠端快取操作的逾時時間（以秒為單位）。

turbo run build --remote-cache-timeout=60

--remote-only

預設值：false

忽略所有任務的本機檔案系統快取，使用遠端快取進行讀取和快取任務輸出。

turbo run build --remote-only

--summarize

在 .turbo/runs 中產生 JSON 檔案，其中包含有關執行的中繼資料，包括

• 受影響的套件
• 已執行的任務（包括其時序和雜湊值）
• 快取成品中包含的所有檔案

turbo run build --summarize

此旗標有助於偵錯，以判斷諸如以下事項

• turbo 如何解譯您的 inputs 和 outputs 的 glob 語法
• 兩個任務執行之間變更了哪些輸入以產生快取未命中
• 任務時序如何隨時間變化

--token

遠端快取的 bearer token。適用於在非互動式 shell 中結合 --team 旗標執行。

turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx

此值也可以使用TURBO_TOKEN 系統變數設定。如果兩者都存在，旗標值將覆寫系統變數。

--team

遠端快取團隊的 slug。適用於在非互動式 shell 中結合 --token 旗標執行。

turbo run build --team=my-team
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx

此值也可以使用TURBO_TEAM 系統變數設定。如果兩者都存在，旗標值將覆寫系統變數。

--ui

指定用於輸出的 UI。接受 stream 或 tui。

--verbosity

若要指定記錄層級，請使用 --verbosity=<num> 或 -v、-vv、-vvv。

turbo run build --verbosity=2
turbo run build -vvv