1. 概述
容器化技术已成为现代应用部署中不可或缺的一部分，Docker Compose 作为定义和运行多容器 Docker 应用的工具，大大简化了开发和运维流程。
但在使用过程中，开发者或 DevOps 工程师可能会遇到一些常见问题，例如执行 docker-compose 命令时报错：docker-compose: command not found。
本篇文章将带你分析该问题的常见原因，并提供多种解决方案，帮助你快速排查和修复该问题。
2. 问题描述
docker-compose 是用于定义和运行多容器 Docker 应用的工具。你可以使用独立的 docker-compose 命令，也可以使用集成在 Docker CLI 中的 Compose 插件（即 docker compose）。
出现 docker-compose: command not found 错误通常有以下几种原因：
- Docker Compose 没有正确安装
docker-compose可执行文件未加入系统环境变量 PATH- 权限不足，无法执行该命令
例如，当你尝试运行：
$ docker-compose up
如果提示如下错误，说明命令未被识别：
docker-compose: command not found
这表明当前系统无法找到 docker-compose 命令。
3. 验证安装
在尝试修复之前，建议先验证 docker-compose 是否已经安装：
$ docker-compose --version
如果安装成功，会输出类似如下内容：
Docker Compose version v2.29.2
如果提示 command not found，说明确实未安装或安装失败。
4. 安装独立版 docker-compose
4.1. 通过二进制文件安装
适用于 Linux 系统，推荐使用以下命令下载最新版本的 docker-compose：
$ sudo curl -L \
https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) \
-o /usr/local/bin/docker-compose
下载完成后，赋予执行权限：
$ sudo chmod +x /usr/local/bin/docker-compose
然后验证是否安装成功：
$ docker-compose --version
4.2. 通过 APT 安装（仅限 Linux）
如果你使用的是基于 Debian/Ubuntu 的 Linux 系统，也可以使用 APT 安装：
$ sudo apt install docker-compose
5. 将 docker-compose 加入 PATH
如果你已经安装了 docker-compose，但仍然报错，可能是其路径未加入环境变量 PATH。
5.1. Linux/macOS
编辑你的 shell 配置文件（如 .bashrc、.zshrc）：
export PATH=$PATH:/usr/local/bin
保存后执行：
$ source ~/.bashrc
5.2. Windows
打开系统环境变量设置：
- 控制面板 → 系统属性 → 环境变量 → 系统变量
- 找到
Path，添加 Docker Compose 的安装路径，通常是：
C:\Program Files\Docker\Docker\resources\bin
6. 安装 Docker CLI 及 Compose 插件
从 Docker 1.5 开始，推荐使用内置的 docker compose 命令代替独立的 docker-compose。这意味着你不再需要单独安装 Compose。
6.1. Linux 安装步骤
首先验证是否已安装 Compose 插件：
$ docker compose version
如果未安装，更新包列表并安装 Docker Engine：
$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io
安装完成后再次验证：
$ docker compose version
从现在开始，建议使用 docker compose 命令替代 docker-compose。
6.2. macOS / Windows 安装
macOS 和 Windows 用户可以直接安装 Docker Desktop，它默认集成了 Docker CLI 和 Compose 插件。
验证是否安装成功：
$ docker --version
如果提示找不到命令，重新安装 Docker Desktop 并重启系统。
7. 处理用户权限问题
如果你是普通用户而非 root 用户，可能会遇到权限问题，导致无法执行 docker-compose 命令：
$ docker-compose --version
zsh: permission denied: docker-compose
查看可执行文件位置：
$ sudo which docker-compose
/usr/local/bin/docker-compose
检查权限：
$ sudo ls -la /usr/local/bin/docker-compose
-rwxr-x--- 1 root root 63173250 Aug 20 01:47 /usr/local/bin/docker-compose
说明该文件只对 root 用户可读可执行。为普通用户添加权限：
$ sudo chmod o+rx /usr/local/bin/docker-compose
再次验证：
$ docker-compose --version
Docker Compose version v2.29.2
✅ 现在你应该可以正常执行命令了。
8. 总结
本文介绍了 docker-compose: command not found 报错的常见原因及解决方法，包括：
- ✅ 验证安装状态
- ✅ 安装独立版
docker-compose - ✅ 设置环境变量 PATH
- ✅ 使用 Docker CLI 的 Compose 插件
- ✅ 处理权限问题
遇到这类问题时不要慌张，按上述步骤逐一排查，基本可以快速定位并修复。保持工具版本更新、环境变量配置正确，是避免此类问题的关键。