Docker Compose profiles 在 Docker Desktop 中启用可选服务的操作步骤

在 Docker Desktop 项目中启用可选服务，最稳妥的做法是把常驻服务和按需服务写在同一个 compose.yaml 中：核心服务不设置 profiles，调试或管理服务绑定 debug 等名称；启动时使用 --profile 或 COMPOSE_PROFILES。这样不需要为每个环境维护一份重复配置。

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

本文中的界面图是原创操作示意图，不是 Docker Desktop 的真实截图。Docker Desktop 的版本、主题和项目面板布局可能不同，实际操作以项目中可见的 Compose 文件和服务状态为准。

步骤1：在 compose.yaml 给可选服务绑定 profile

先在项目根目录准备 compose.yaml。没有 profiles 的服务始终参与 Compose 模型；写了 profiles: [debug] 的服务，只有 debug 被激活时才会参与。下面用 web 和 db 表示常驻服务，用 adminer 表示调试时才需要的管理服务。

services:
  web:
    image: example/web:latest
    # 核心服务不绑定 profile，默认随项目启动
    depends_on:
      - db

  db:
    image: postgres:18
    # 数据库也保持常驻，避免调试服务单独启动时缺少依赖

  adminer:
    image: adminer:latest
    # 只有激活 debug 时才纳入项目模型
    profiles: [debug]
    depends_on:
      - db

保存后重点看三件事：profiles 写在服务下面而不是顶层；名称只使用字母、数字、下划线、点或连字符组成的有效标识；依赖关系要和启用策略一致。若 adminer 依赖的服务也被另一个 profile 隔离，激活 debug 时可能出现依赖不在当前模型中的错误。

步骤2：从 Docker Desktop 项目入口打开 Compose 操作

打开 Docker Desktop 后进入对应项目或容器工作区，先确认当前项目使用的 Compose 文件就是刚才保存的 compose.yaml。如果目录中同时存在多个 Compose 文件，先确认项目的文件组合与工作目录，不要只根据服务名称判断。

Docker Desktop 可以作为项目的可视化入口，但 profile 的启用仍由 Docker Compose 命令决定。可在 Docker Desktop 集成终端、项目脚本或外部终端执行命令；本文只关注命令参数和 Docker Desktop 中最终能看到的服务状态，不把界面位置当成固定版本契约。

执行前先关闭同一项目中不需要的旧状态，或者明确知道自己要更新的是哪个 Compose project。项目名称不一致时，命令可能创建另一组服务，看起来像 profile 没有生效，实际是打开了不同项目。

步骤3：用 --profile 或 COMPOSE_PROFILES 启动可选服务

需要调试服务时，在项目目录执行下面任一种方式。两种写法的目标相同，命令行参数适合临时操作，环境变量适合脚本或团队约定。

# 临时启用 debug，核心服务仍会一并启动
docker compose --profile debug up -d

# 用环境变量表达同样的选择，适合放进项目脚本
COMPOSE_PROFILES=debug docker compose up -d

# 同时启用多个 profile，名称之间用逗号分隔
COMPOSE_PROFILES=debug,frontend docker compose up -d

按 Docker Compose 规则，无 profile 的 web、db 会继续参与；匹配 debug 的 adminer 才会加入。多个 profile 可以重复传递 --profile，也可以在 COMPOSE_PROFILES 中使用逗号分隔。需要只运行一个明确的 profile 服务时，也可以直接指定服务名；但它的依赖仍必须存在于可用模型中。

步骤4：用配置模型确认结果，异常时回退

不要只看 Docker Desktop 中是否出现了容器，可以用 Compose 的配置命令核对当前模型。下面的命令只查看服务与 profile 名称，不会把排查过程变成额外的项目配置。

# 查看当前启用选择下会出现哪些服务
docker compose config --services

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

# 临时清空环境变量，回到只启动核心服务的默认状态
COMPOSE_PROFILES= docker compose up -d

启用 debug 时，服务列表应包含 web、db 和 adminer；未启用时通常只包含没有 profile 的核心服务。若命令行显式写了 --profile，它会覆盖同一选项的环境变量设置，因此排查时要把参数和环境变量一起看。

Docker Desktop 里找不到 profile 开关怎么办？不要把它当成必须存在的图形按钮。直接在项目目录使用 Compose 的 --profile 参数，Docker Desktop 会显示对应项目和容器状态。

能不能把所有服务都加上 profile？不建议。核心服务不绑定 profile 更容易保持默认启动路径，只有真正按环境或任务切换的服务才适合隔离。

如何快速回到默认启动？移除当前 shell 中的 COMPOSE_PROFILES，并不要传入 --profile；再用 docker compose config --services 对照服务集合。