旧版 Docker Compose v1 升级到 v2 命令行参数变化有哪些不同

升级 Docker Compose 从 v1 到 v2 最核心的变化是命令调用方式，从独立命令 docker-compose 变为 Docker CLI 插件 docker compose（中间有空格）。最稳妥的做法是先在测试环境验证配置文件，检查弃用字段后再逐步迁移到生产环境。

先说结论：Docker Compose v1 到 v2 主要是命令格式和配置语法的变更，核心服务定义大部分兼容，但需要检查弃用字段和工具链版本。

• 先确认：当前环境的 Docker 和 Compose 版本，避免混用导致命令解析失败
• 先处理：移除 extends 等已弃用字段，改用多文件组合或 YAML 锚点
• 再验证：用docker compose config检查配置有效性后再部署

V2 插件式安装指南

Docker Compose v2 官方推荐作为 Docker CLI 插件安装，这样可以直接使用 docker compose 命令。避免安装独立二进制文件导致命令冲突。

# Ubuntu/Debian 系统
sudo apt-get update
sudo apt-get install docker-compose-plugin

# CentOS/RHEL 系统
sudo yum install docker-compose-plugin

# 验证安装是否成功（注意中间有空格）
docker compose version

如果必须手动安装二进制文件，请确保将其放置在 CLI 插件目录，否则无法使用 docker compose 命令：

mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

命令速用版

最核心的变化是命令中间的空格。旧版是独立命令，新版是 Docker CLI 的子命令。

# 检查当前版本
docker compose version

# 启动服务 (旧写法)
docker-compose up -d

# 启动服务 (新写法)
docker compose up -d

# 查看配置有效性
docker compose config

# 修改实例数 (v1)
docker-compose scale web=3

# 修改实例数 (v2)
docker compose up `--scale` web=3 -d

分步处理

第一步：备份现有配置

cp docker-compose.yml docker-compose.yml.bak

第二步：检查命令调用方式

搜索项目中所有调用 Compose 的地方 (包括 CI 配置文件、部署脚本、文档)，将docker-compose改为docker compose。如果团队环境不统一，可以暂时保留两个命令都能用的方式。

第三步：处理弃用字段

检查docker-compose.yml中是否有以下字段：

• extends：改用多文件组合或 YAML 锚点
• version：v2 中可移除，不再需要显式声明
• 自定义字段：确保都以x-开头

第四步：检查容器命名规则

容器命名规则从下划线分隔 (如project_service_1) 变更为连字符分隔 (如project-service-1)，依赖硬编码容器名的脚本会因此失效。

怎么验证是否生效

执行以下命令确认迁移完成：

# 验证版本
docker compose version

# 验证配置文件是否兼容
docker compose config

# 启动服务测试
docker compose up -d

# 查看运行状态
docker compose ps

如果docker compose config能正常输出配置且无警告，说明语法兼容。如果启动后docker compose ps能正常显示服务，说明命令调用正确。

常见坑

• CI/CD 流水线命令不统一：这个改动看似小，但在 CI/CD 流水线中如果环境不统一，极易导致构建失败。建议优先在测试环境验证网络模式和服务命名变化。
• version 字段报错：对于报错ERROR: Version in "./docker-compose.yml" is unsupported，需将版本字段调整为version: '3.8'或移除该字段 (V3+ 版本隐式化)。
• deploy 配置被忽略：注意deploy配置仅在 Swarm 模式或支持 Compose Specification 的环境中生效，非 Swarm 模式下会被忽略。
• 环境变量加载优先级：V2 定义了环境变量加载的优先级，配置文件.env 中特殊情况下的行为，如转义嵌套等，V1 中没有定义环境变量的行为，在极端情况下可能会产生行为不一致的情况。
• 扩展字段校验：v2 要求所有自定义字段必须以x-开头，旧版工具链可能忽略未知字段，但 v2 兼容的编排引擎会严格校验 Schema，未规范使用的扩展字段可能导致部署失败。

原文链接：https://www.zjcp.cc/ask/11066.html