run

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

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

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

如果未提供任何任務，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 <options>

預設值：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 <path>

預設值：.turbo/cache

指定檔案系統快取目錄。

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

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

--concurrency <number | percentage>

預設值：10

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

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

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

--continue

預設值：false

在出現錯誤的情況下（例如，任務的非零結束代碼）繼續執行任務。

當 --continue 為 true 時，turbo 將會以執行期間遇到的最高結束代碼值結束。

turbo run build --continue

--cwd <path>

預設值：根目錄 turbo.json 的目錄

設定命令的工作目錄。

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

--dangerously-disable-package-manager-check

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

為了協助增量移轉，或是您無法使用 packageManager 欄位的情況，您可以使用 --dangerously-disable-package-manager-check 來選擇不進行此檢查，並承擔不穩定鎖定檔產生不可預測行為的風險。停用時，Turborepo 會盡力探索儲存庫的目標套件管理器。

--dry / --dry-run

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

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

任務詳細資訊包含有用的資訊，例如（列表不詳盡）

--env-mode <option>

類型：字串

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

turbo run build --env-mode=loose

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

strict

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

• env
• passThroughEnv
• globalEnv
• globalPassThroughEnv

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

loose

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

--filter <string>

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

可以合併篩選器，以建立套件、目錄和 Git 提交的組合。

篩選的微語法

• !：從選取中否定目標。
• ... 使用套件：選取套件圖中相對於目標的所有套件。在套件名稱之前使用 ... 將會選取目標的從屬項，而在套件名稱之後使用 ... 將會選取目標的相依性。
• ... 使用 Git 提交：使用 [<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

控制執行任務時產生的記錄行的 <package>:<task>: 前綴。

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

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

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 權杖。在非互動式 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