Docker Compose --profile 与 profiles 环境变量怎样区分

Docker Compose 里最容易混淆的不是 profiles 语法，而是“谁在决定 profile”。services 下的 profiles 是服务声明；命令行的 --profile 是一次运行时选择；COMPOSE_PROFILES 则是 Compose CLI 读取的预定义环境变量。三者配合使用时，默认服务仍会启动，只有匹配的可选服务才会加入。

官方地址：https://docs.docker.com/compose/how-tos/profiles/

本文用一份带 debug 和 tools 的 Compose 配置说明选择关系，不讨论容器内应用变量的注入细节。示例是原创操作示意，命令输出需要在你的项目环境中自行查看。

先把默认服务和可选服务分开

没有 profiles 属性的服务始终属于默认集合；带有 profiles 的服务只有在对应 profile 被启用时，才会随整体启动。实际项目里可以让数据库和后端保持默认，把调试面板、迁移任务或本地工具放到可选 profile。

services:
  api:
    image: example/api:dev
    # 核心服务不设置 profiles，默认 docker compose up 就会启动
    environment:
      APP_ENV: ${APP_ENV:-dev}

  db:
    image: postgres:16
    # 数据库同样保持在默认集合中，供 api 依赖

  adminer:
    image: adminer:latest
    profiles: [debug]
    # 只有启用 debug 时才加入整体启动

  migrate:
    image: example/api:dev
    command: ["./app", "migrate"]
    profiles: [tools]
    # 一次性迁移工具单独放到 tools，避免每次 up 都执行

这里的关键是声明位置：profiles 写在服务对象上，不是写在 environment 里。合法 profile 名称由字母、数字、下划线、点和短横线组成，并且第一个字符不能是分隔符。

临时选择用 --profile

只想在本次命令中打开调试服务时，优先使用命令行参数。--profile 放在 up 前面；可以重复传入多个 profile。没有 profile 的 api 和 db 仍会启动。

# 临时打开 debug，保留所有默认服务
docker compose --profile debug up -d

# 同时打开 debug 和 tools，多个 profile 可以重复传参
docker compose --profile debug --profile tools up -d

# 只想运行被 profile 保护的一次性服务，可以直接点名
docker compose run --rm migrate

直接点名 migrate 时，Compose 会自动允许这个被 profile 保护的服务运行，并按 depends_on 启动它声明的依赖；同 profile 的其他服务不会因为这次点名而全部启动。如果你的目标是打开整组服务，仍然显式写 --profile 更清楚。

固定选择用 COMPOSE_PROFILES

当团队希望把“开发环境默认打开哪些可选服务”放进启动配置，可以用预定义变量 COMPOSE_PROFILES。它表达的是 Compose 当前启用的 profile 集合，不等同于把一个名为 COMPOSE_PROFILES 的变量传进容器。

# 当前 shell 会话启用 debug 和 tools
export COMPOSE_PROFILES=debug,tools
docker compose up -d

# 只影响这一条命令，结束后不会改动 shell
COMPOSE_PROFILES=debug docker compose up -d

# 用专门的环境文件保存这一组 Compose CLI 选择
docker compose --env-file .env.debug up -d

# .env.debug：这是给 Compose CLI 读取的预定义变量
COMPOSE_PROFILES=debug
APP_ENV=dev

如果同时写了 --profile debug 和 COMPOSE_PROFILES=tools，不要把它们当成两个互相覆盖的配置文件来理解；为避免团队脚本产生歧义，建议每条入口只选一种主控方式。要切换配置文件，使用 --env-file；它负责提供变量来源，真正控制 profile 集合的键仍然是 COMPOSE_PROFILES。

用 config 看清最终选择

不要只凭启动日志判断 profile 是否生效。config 可以把 Compose 解析后的模型打印出来，--profiles 显示文件中出现过的 profile 名称，--environment 显示用于插值的环境。下面的检查只观察配置解析，不会替你证明镜像已经成功运行。

# 列出 compose.yaml 中声明过的 profile 名称
docker compose config --profiles

# 查看本次插值使用的环境来源
docker compose --env-file .env.debug config --environment

# 查看最终规范化配置，确认 adminer 是否出现在模型里
docker compose --profile debug config

如果 adminer 不在默认的 docker compose config 输出里，这是预期行为；加上 --profile debug 后再看。若 COMPOSE_PROFILES 写进了 .env 却没有效果，先确认当前项目目录、--project-directory 和 --env-file 指向的文件，因为 Compose 的变量插值来源有优先级。

常见误区和最后确认

误区一：把 profiles 当成容器环境变量。它控制 Compose 是否纳入服务；应用真正需要的变量仍应通过服务的 environment、env_file 或 secrets 等方式提供。

误区二：以为 .env 会自动传进容器。.env 默认主要用于 Compose 插值和 CLI 自身配置；只有在服务配置里明确引用，变量才会进入容器环境。

误区三：忘记默认服务。启用 profile 不会只启动该 profile 的服务，无 profile 的服务也会一起纳入。若要只执行迁移工具，使用点名命令并检查它的依赖。

可以按这张小表做最后选择：

一句话记忆：profiles 决定服务属于哪一组，--profile 决定本次命令打开哪一组，COMPOSE_PROFILES 把这次选择写成 Compose CLI 可读取的环境配置。

相关问题

为什么不写 profiles 的服务总会启动？因为它们属于默认服务集合，Compose 不要求额外启用 profile。

多个 profile 怎样同时启用？命令行重复传入 --profile，或在 COMPOSE_PROFILES 中使用逗号分隔。

为什么直接 run 一个工具不用先写 --profile？显式点名服务时，Compose 会自动允许该服务运行，但不会自动打开同 profile 的其它服务。