1.2 安装与版本选择

1.2 安装与版本选择

本节摘要：安装 Compose 有三条主流路径：Docker Desktop 自带插件、Linux 发行版包、独立二进制。比安装更值得先搞清楚的是版本问题：docker-compose 连字符写法是 V1 时代的 Python 实现，docker compose 空格写法是 V2 的 Go 实现，两者在语法、性能和维护状态上差异明显。本节还说明一个常被旧教程误导的事实：version 字段已被弃用，新版文件可以不写。

本节目标

• 能说清 docker-compose 与 docker compose 两种写法的版本归属与差异
• 能根据操作系统选择最省事的安装方式并完成安装
• 能用版本命令验证安装结果
• 能解释为什么旧教程里的 version 字段现在可以省略
• 能判断一条网上抄来的 Compose 语法是否适用于当前版本

一、先分清两个名字，再谈安装

打开任何一篇 2019 年之前的 Docker 教程，命令都是 docker-compose up，带连字符。而现在的官方文档写作 docker compose up，带空格。这两个写法不是笔误，而是两个时代的产物。

docker-compose（连字符）是 Compose V1，用 Python 写的独立程序，通过 pip 或二进制分发。docker compose（空格）是 Compose V2，用 Go 重写，从 2021 年起成为 Docker CLI 的官方子命令，随 Docker 引擎一起分发，不再需要单独安装。V2 在启动速度、内存占用和错误信息上全面优于 V1，而且从 2023 年起 Docker 官方不再维护 V1。结论很直接：新环境一律用 docker compose 空格写法，看到旧教程里的连字符命令，心里要自动换算。

时间线能解释为什么网上到处是连字符教程：Compose V2 在 2020 年发布预览，2021 年随 Docker Desktop 和 Docker Engine 逐步成为默认子命令，2022 年起官方文档全面转向空格写法。也就是说，2022 年之前出版的教程和博客几乎清一色是连字符，它们教的语法大部分仍然有效，但命令写法已经过时。另一个容易被忽略的差异是文件名：V2 时代 Compose 文件仍然认 docker-compose.yml，官方现在更推荐 compose.yaml 这个新名字，但旧名字完全兼容，不必为此改文件。真正要留心的是那些 V2 已移除的旧特性，比如部分顶层键的旧写法，遇到报错再去查官方文档确认即可。

二、安装方式一：Docker Desktop 自带插件

如果你在 Windows 或 macOS 上工作，最省事的路径是装 Docker Desktop。它把 Docker 引擎、CLI、Compose 插件、图形界面打包在一起，安装向导走完，docker compose 就已经可用了。

装完后打开终端验证：

docker compose version
​

能打印出版本号（例如 Docker Compose version v2.23.0 之类）就说明插件已就位。Windows 上如果命令找不到，多半是 Docker Desktop 没启动，或者终端没有重开导致 PATH 没刷新。macOS 上还要注意 Apple 芯片与 Intel 芯片的安装包不通用，下载时看清架构。Windows 上还有一个容易绕晕的点：Docker Desktop 有 Linux 容器与 Windows 容器两种模式，本书所有模板都是为 Linux 容器写的，确认自己跑在 Linux 容器模式，否则镜像、卷、网络的行为都会对不上。

Docker Desktop 适合个人开发和本地实验，缺点是它自带一个轻量虚拟机（Windows 上是 WSL2 后端，macOS 上走 Hypervisor），占用资源偏大，服务器上一般不用它。安装完成后建议先动两处设置：一是资源选项卡，给虚拟机分配的内存和 CPU 别默认全吃，留一半给宿主系统，尤其是内存只有 8G 的笔记本；二是把镜像源配置成可用的加速地址，否则拉镜像会等得怀疑人生。这两处配好，本地开发体验会顺很多。

三、安装方式二：Linux 发行版包

Linux 服务器上，最正规的路径是发行版包管理器。Docker 官方源里带一个名为 docker-compose-plugin 的包，装上之后 docker compose 子命令即生效。

# Debian/Ubuntu
sudo apt update
sudo apt install docker-compose-plugin
# CentOS/RHEL
sudo yum install docker-compose-plugin
​

前提是 Docker 引擎本身已经安装，并且 apt 或 yum 配置了 Docker 官方软件源。如果用的是国内镜像源，需要先把官方源换成可访问的镜像地址，否则 apt update 会拉不到这个包。装包之前建议先跑 docker --version 确认引擎就绪——Compose 插件只是给 CLI 加一个子命令，引擎不在，装完也是白搭。这一步省不得，社区里"装完 Compose 却提示 Cannot connect to the Docker daemon"的求助帖，根因多半是引擎没起来或者当前用户没权限连上引擎。

发行版包的优点是和 Docker 引擎版本一起由包管理器统一管理，升级、卸载都干净。升级时只需重新执行一次安装命令，包管理器会拉取新版本替换旧文件；卸载用 apt remove docker-compose-plugin 或对应的 yum remove，配置文件和已下载的镜像不受影响。缺点是要等发行版仓库的同步节奏，可能拿不到最新版。对生产服务器来说，这通常不是问题——稳定比新更重要。

四、安装方式三：独立二进制

不想引入包管理依赖，或者发行版仓库太老，可以下载官方发布的独立二进制。Compose 在 GitHub Releases 页面按平台和架构发布编译好的文件，以 Linux x86_64 为例：

sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version
​

把 URL 里的 v2.23.0 换成你查到的当前最新版本号即可。注意这里的下载路径带连字符命令名 docker-compose，因为独立二进制沿用 V1 的命名习惯；它实际是 V2 的编译产物，装完既可以跑 docker-compose 连字符命令，也可以在配置后作为 docker compose 子命令被调用。

两个容易踩的坑：一是忘了 chmod +x，直接执行会报 Permission denied；二是下载到一半断网，文件残缺，验证时提示无法执行二进制文件。建议下载后用版本命令验证，输出的版本号不对就重下。升级独立二进制同样简单：下载新版本文件覆盖 /usr/local/bin/docker-compose，再赋予执行权限即可，旧文件被直接替换，不用先卸载。国内服务器从官方 Releases 下载可能很慢，可以先用加速地址把文件拉到本地，校验无误后再传到服务器安装。

五、pip 安装：曾经的主流，如今请谨慎

老教程里常见的 pip 安装方式值得单独说一句：

pip install docker-compose
python3 -m pip install --user docker-compose
export PATH=$PATH:~/.local/bin
​

把 export 一行写进 .bashrc 或 .zshrc 再 source 一下，就能永久生效。这套流程本身没毛病，但它安装的是 Python 版 Compose V1，而 V1 已经停止维护，与新版 Compose 文件规范的兼容性会越来越差。除非你维护的旧项目锁死了 V1，否则不建议新环境用 pip 装 Compose。pip 装 V1 的另一层风险是它依赖一堆 Python 包，可能与系统里其他 Python 项目互相污染版本。如果已经装了想卸载，pip uninstall docker-compose 即可，用户级安装加上 --user 参数同样生效。

六、验证安装与初始化配置

无论哪条路径，装完只做一件事：跑版本命令。

docker compose version
​

看到版本号即成功。Compose 本身通常不需要额外配置，它读取 Docker 引擎的配置，你真正要关心的是 Docker daemon 的配置，比如镜像加速地址、日志驱动、资源上限，这些写在 Docker 引擎的配置文件里，Compose 不碰它们。项目级配置则全部收敛在 docker-compose.yml 与 .env 里，这一点在 1.3 节展开。版本命令还有一个常见变体值得留意：旧版独立二进制用 docker-compose --version，新版插件用 docker compose version，两者输出格式也不同。如果机器上两个命令都能跑，说明 V1 与 V2 并存，优先使用 docker compose，并考虑卸载旧版，避免两个版本对同一份文件给出不同行为。

验证通过之后还有两个高频问题值得提前交代。一是权限：Linux 上普通用户执行 docker 命令报权限不足，是因为当前用户不在 docker 用户组里，把用户加入 docker 组并重新登录即可，不要用 sudo 硬跑 Compose，否则生成的卷和容器文件属主会乱。二是引擎连通性：docker compose version 只能证明插件存在，证明不了引擎可用，接着跑 docker info 确认 Docker daemon 正常，再进入下一步。

七、版本选择：version 字段已被弃用

这是本节最反直觉的一点，也是旧教程最大的历史包袱。早期的 Compose 文件开头都要写一行：

version: "3.9"
​

当时的逻辑是：文件版本号决定 Compose 解释器启用哪些语法特性。但从 Compose V2 开始，这行字的作用被移除了——V2 全面支持旧版本文件的写法，version 字段不再改变任何解析行为，写不写、写 3.8 还是 3.9，结果完全一样。官方做法是直接删掉这一行，让文件从 services 块开始。Compose 文件格式的演进现在由独立的 Compose 规范（compose-spec）维护，不再按版本号割裂功能。规范文档本身值得收藏：它定义了所有顶层键与子键的类型和默认值，是判断一段配置写法是否合法的最终依据。

所以遇到网上抄来的配置，判断规则是：看命令写法——docker-compose 连字符多半是老文，要留心 deprecated 语法；docker compose 空格写法基本可以直接用。看到文件里带 version 字段，知道它无害但多余即可，不必大惊小怪。

环境变量 COMPOSE_FILE 是另一个值得知道的开关：默认情况下 Compose 自动找当前目录的 docker-compose.yml 或 compose.yaml，而 COMPOSE_FILE 可以指定任意路径，甚至用冒号分隔指定多个文件。多文件组合是大型项目的常见手法：基础文件放公共服务，覆盖文件放环境差异，运行时用 COMPOSE_FILE=base.yml:prod.yml docker compose up -d 组合生效。这个变量也解释了为什么有人把 Compose 文件放在 deploy 子目录而不是项目根目录——配合 COMPOSE_FILE 或 -f 参数，文件放哪都不影响使用。

最后给一条版本选择的总建议：Docker 引擎跟随官方稳定版本升级，Compose 插件随引擎一起更新，不要单独追最新版。新项目从第一天就用 docker compose 空格写法、省略 version 字段；存量项目迁移时，先跑 docker compose config 验证旧文件，确认无报错再逐步清理历史包袱。

安装方式决策流程

三种安装方式对比

⚠️ 装完先跑版本命令：安装过程中最常见的失败是"命令找不到"或"权限不足"，版本命令一次能验证路径、权限、完整性三件事。任何安装教程看完，第一步永远是 docker compose version。

💡 新旧判断口诀：看到 docker-compose 连字符，先想"这是 V1 时代的写法"；看到 docker compose 空格，放心用。文件里的 version 字段可以删，命令里的连字符不能混着抄。

一节小结

• 两种写法两个时代：docker-compose 连字符是 Python 版 V1，docker compose 空格是 Go 版 V2，官方已停止维护 V1
• Docker Desktop 最省事：Windows 和 macOS 用户装完桌面版即自带 Compose 插件
• Linux 首选发行版包：apt 或 yum 安装 docker-compose-plugin，随系统统一管理
• 独立二进制要 chmod +x：下载官方 Release 的二进制后必须赋予执行权限，否则报权限错误
• pip 装的是 V1：已停止维护，新环境不建议，除非项目锁死旧版
• version 字段已弃用：V2 不再依赖文件版本号决定语法，这行可以直接删掉
• Compose 规范独立演进：文件格式由 compose-spec 维护，按功能演进而非版本割裂

工具就绪，下一步该读文件了——1.3 节拆解 docker-compose.yml 的顶层块和常用键，附一份带注释的最小示例，那是你照着写的第一张配方卡。