在 Docker Compose 中設定或變更預先定義的環境變數

目錄

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_MENU
  • COMPOSE_EXPERIMENTAL

覆蓋方法

您可以設定或變更預先定義的環境變數

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

設定

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=docker-compose.yml:docker-compose.prod.yml
    也可以使用 `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_CONVERT_WINDOWS_PATHS

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

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

COMPOSE_PATH_SEPARATOR

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

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

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_ENV_FILES

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

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

COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2

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

COMPOSE_MENU

Docker Compose 2.26.0 版引入

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

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

COMPOSE_EXPERIMENTAL

Docker Compose 2.26.0 版引入

這是一個選擇性停用的變數。關閉後，它會停用實驗性功能，例如導覽選單或同步檔案共享。

  • 支援的值
    • `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 會使用傳統建置器來建置映像檔。