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

目錄

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

此頁面包含有關如何在需要時設定或更改以下預定義環境變數的資訊

  • COMPOSE_CONVERT_WINDOWS_PATHS
  • COMPOSE_FILE
  • COMPOSE_PROFILES
  • COMPOSE_PROJECT_NAME
  • DOCKER_CERT_PATH
  • COMPOSE_PARALLEL_LIMIT
  • COMPOSE_IGNORE_ORPHANS
  • COMPOSE_REMOVE_ORPHANS
  • COMPOSE_PATH_SEPARATOR
  • 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 或 docker-compose.yaml 的檔案，如果未找到，Compose 會遞迴搜尋每個父目錄，直到找到該名稱的檔案。
  • 預設分隔符：指定多個 Compose 檔案時，路徑分隔符預設情況下為
    • Mac 和 Linux：:（冒號），
    • Windows：;（分號）。

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

示例：COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml。

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

COMPOSE_PROFILES

指定在 compose up 執行時要啟用的一個或多個配置檔案。具有匹配配置檔案的服務將啟動，以及任何未定義配置檔案的服務。

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

  • 預設分隔符：使用逗號作為分隔符來指定配置檔案列表。

示例：COMPOSE_PROFILES=frontend,debug
此示例啟用所有與 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_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

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

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

COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2

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

COMPOSE_MENU

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

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

注意

在 Docker Compose 版本 2.26.0 及更高版本以及 Docker Desktop 版本 4.29 及更高版本中可用

COMPOSE_EXPERIMENTAL

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

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

注意

在 Docker Compose 版本 2.26.0 及更高版本以及 Docker Desktop 版本 4.29 及更高版本中可用

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 使用經典構建器構建映象。