GitLab CI执行docker compose报错‘compose不是docker命令’原因排查

问题原因 #

你遇到的问题核心是GitLab CI的运行环境和服务器本地环境完全隔离：

• 你的deploy job使用了docker:latest官方镜像，这个镜像仅预装了Docker CLI，没有包含Docker Compose v2的CLI插件，所以执行docker compose会提示命令不存在。
• 你在CI里看到的docker-compose version 1.25.0是这个镜像自带的旧版Compose（v1），和服务器本地安装的v2.26.0无关——CI job是在独立容器内运行，不会复用宿主机上的软件。

解决方案 #

方案1：使用预装Docker Compose v2的镜像 #

直接改用docker/compose官方镜像，它已经集成了Docker CLI和Compose v2插件，无需额外安装：

deploy:
  image: docker/compose:2.26.0 # 也可以用latest获取最新版
  before_script:
    - docker version
    - docker compose version
  script:
    - docker info

方案2：在docker:latest镜像中手动安装Compose v2插件 #

如果必须使用docker:latest镜像，可在before_script中添加安装步骤（基于Alpine系统的命令）：

deploy:
  image: docker:latest
  before_script:
    - docker version
    # 安装依赖并下载Compose v2插件
    - apk add --no-cache curl
    - curl -SL https://github.com/docker/compose/releases/download/v2.26.0/docker-compose-linux-x86_64 -o /usr/local/lib/docker/cli-plugins/docker-compose
    - chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
    # 验证安装
    - docker compose version
  script:
    - docker info

方案3：继续使用旧版docker-compose（不推荐） #

如果暂时需要兼容旧语法，可继续使用docker-compose命令，但要注意CI环境的v1.25.0和本地v2.26.0的语法差异——v1已被官方废弃，长期来看建议升级到v2。

内容的提问来源于stack exchange，提问作者Alex Dalen