在 Docker Compose 中配置預定義環境變數

Docker Compose 包含幾個預定義的環境變數。它還繼承了常見的 Docker CLI 環境變數，例如 DOCKER_HOST 和 DOCKER_CONTEXT。有關詳細資訊，請參閱Docker CLI 環境變數參考。

本頁解釋如何設定或更改以下預定義環境變數

• COMPOSE_PROJECT_NAME
• COMPOSE_FILE
• COMPOSE_PROFILES
• COMPOSE_CONVERT_WINDOWS_PATHS
• COMPOSE_PATH_SEPARATOR
• COMPOSE_IGNORE_ORPHANS
• COMPOSE_REMOVE_ORPHANS
• COMPOSE_PARALLEL_LIMIT
• COMPOSE_ANSI
• COMPOSE_STATUS_STDOUT
• COMPOSE_ENV_FILES
• COMPOSE_DISABLE_ENV_FILE
• COMPOSE_MENU
• COMPOSE_EXPERIMENTAL
• COMPOSE_PROGRESS

覆蓋方法

更改或設定任何環境變數時，請注意環境變數優先順序。

配置詳情

專案和檔案配置

COMPOSE_PROJECT_NAME

設定專案名稱。此值在啟動時與服務名稱一起新增到容器名稱的前面。

例如，如果您的專案名稱是 myapp 並且它包含兩個服務 db 和 web，那麼 Compose 會分別啟動名為 myapp-db-1 和 myapp-web-1 的容器。

Compose 可以透過不同的方式設定專案名稱。每種方法的優先順序（從高到低）如下：

1. -p 命令列標誌
2. COMPOSE_PROJECT_NAME
3. 配置檔案中的頂級 name: 變數（或使用 -f 指定的一系列配置檔案中的最後一個 name:）
4. 包含配置檔案的專案目錄的 basename（或包含使用 -f 指定的第一個配置檔案的目錄）
5. 如果未指定配置檔案，則為當前目錄的 basename

專案名稱必須只包含小寫字母、十進位制數字、短劃線和下劃線，並且必須以小寫字母或十進位制數字開頭。如果專案目錄或當前目錄的 basename 違反此約束，則必須使用其他機制之一。

另請參閱命令列選項概述和使用 -p 指定專案名稱。

COMPOSE_FILE

指定 Compose 檔案的路徑。支援指定多個 Compose 檔案。

• 預設行為：如果未提供，Compose 會在當前目錄中查詢名為 compose.yaml 的檔案，如果找不到，則 Compose 會遞迴搜尋每個父目錄，直到找到該名稱的檔案。
• 指定多個 Compose 檔案時，預設情況下路徑分隔符為：

  • Mac 和 Linux：:（冒號）

  • Windows：;（分號）例如

    COMPOSE_FILE=compose.yaml:compose.prod.yaml
    

  路徑分隔符也可以使用COMPOSE_PATH_SEPARATOR進行自定義。

另請參閱命令列選項概述和使用 -f 指定一個或多個 Compose 檔案的名稱和路徑。

COMPOSE_PROFILES

指定在執行 docker compose up 時要啟用一個或多個配置檔案。

具有匹配配置檔案的服務以及未定義任何配置檔案的服務都將啟動。

例如，使用 COMPOSE_PROFILES=frontend 呼叫 docker compose up 會選擇具有 frontend 配置檔案的服務以及未指定配置檔案的任何服務。

如果指定多個配置檔案，請使用逗號作為分隔符。

以下示例啟用所有匹配 frontend 和 debug 配置檔案的服務以及沒有配置檔案的服務。

COMPOSE_PROFILES=frontend,debug

另請參閱將配置檔案與 Compose 結合使用和--profile 命令列選項。

COMPOSE_PATH_SEPARATOR

為 COMPOSE_FILE 中列出的項指定不同的路徑分隔符。

• 預設為
  • 在 macOS 和 Linux 上為 :
  • 在 Windows 上為;

COMPOSE_ENV_FILES

指定如果未使用 --env-file，Compose 應使用哪些環境檔案。

使用多個環境檔案時，請使用逗號作為分隔符。例如

COMPOSE_ENV_FILES=.env.envfile1,.env.envfile2

如果未設定 COMPOSE_ENV_FILES，並且您未在 CLI 中提供 --env-file，Docker Compose 將使用預設行為，即在專案目錄中查詢 .env 檔案。

COMPOSE_DISABLE_ENV_FILE

允許您停用使用預設的 .env 檔案。

• 支援的值
  • true 或 1，Compose 會忽略 .env 檔案
  • false 或 0，Compose 會在專案目錄中查詢 .env 檔案
• 預設為：0

環境處理和容器生命週期

COMPOSE_CONVERT_WINDOWS_PATHS

啟用後，Compose 會在卷定義中執行從 Windows 樣式到 Unix 樣式的路徑轉換。

• 支援的值
  • true 或 1，啟用
  • false 或 0，停用
• 預設為：0

COMPOSE_IGNORE_ORPHANS

啟用後，Compose 不會嘗試檢測專案的孤立容器。

• 支援的值
  • true 或 1，啟用
  • false 或 0，停用
• 預設為：0

COMPOSE_REMOVE_ORPHANS

啟用後，Compose 會在更新服務或堆疊時自動刪除孤立容器。孤立容器是那些由先前的配置建立但不再在當前 compose.yaml 檔案中定義的容器。

• 支援的值
  • true 或 1，啟用自動刪除孤立容器
  • false 或 0，停用自動刪除。Compose 會改為顯示有關孤立容器的警告。
• 預設為：0

COMPOSE_PARALLEL_LIMIT

指定併發引擎呼叫的最大並行度。

輸出

COMPOSE_ANSI

指定何時列印 ANSI 控制字元。

• 支援的值
  • auto，Compose 會檢測是否可以使用 TTY 模式。否則，使用純文字模式
  • never，使用純文字模式
  • always 或 0，使用 TTY 模式
• 預設為：auto

COMPOSE_STATUS_STDOUT

啟用後，Compose 會將其內部狀態和進度訊息寫入 stdout 而不是 stderr。預設值為 false，以明確區分 Compose 訊息和容器日誌之間的輸出流。

• 支援的值
  • true 或 1，啟用
  • false 或 0，停用
• 預設為：0

COMPOSE_PROGRESS

定義進度輸出的型別，如果未使用 --progress。

支援的值為 auto、tty、plain、json 和 quiet。預設為 auto。

使用者體驗

COMPOSE_MENU

啟用後，Compose 會顯示一個導航選單，您可以在其中選擇在 Docker Desktop 中開啟 Compose 堆疊，切換到watch 模式，或使用Docker Debug。

• 支援的值
  • true 或 1，啟用
  • false 或 0，停用
• 預設為：如果您透過 Docker Desktop 獲取 Docker Compose，則為 1；否則預設為 0

COMPOSE_EXPERIMENTAL

這是一個選擇退出變數。關閉後會停用實驗性功能。

• 支援的值
  • true 或 1，啟用
  • false 或 0，停用
• 預設為：1

Compose V2 不支援

以下環境變數在 Compose V2 中無效。有關詳細資訊，請參閱遷移到 Compose V2。

• COMPOSE_API_VERSION 預設情況下，API 版本與伺服器協商。使用 DOCKER_API_VERSION。
  請參閱Docker CLI 環境變數參考頁面。
• COMPOSE_HTTP_TIMEOUT
• COMPOSE_TLS_VERSION
• COMPOSE_FORCE_WINDOWS_HOST
• COMPOSE_INTERACTIVE_NO_CLI
• COMPOSE_DOCKER_CLI_BUILD 使用 DOCKER_BUILDKIT 選擇 BuildKit 和經典構建器。如果 DOCKER_BUILDKIT=0，則 docker compose build 使用經典構建器來構建映象。