如果你正在从 Docker Compose V1 迁移到 V2，最稳妥的做法是先在测试环境验证配置文件，确认命令从docker-compose改为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

配置调整重点

Docker Compose V2 不再是独立二进制，而是集成到 Docker CLI 中。配置语法上，V2 对部分字段进行了规范化，以下是需要重点调整的内容：

1. version 字段

version字段在 V2 中不再需要显式声明，旧写法会触发警告但不影响运行。建议在新配置中移除该字段。

2. extends 字段兼容性

误区纠正：extends字段在 V2 本地文件中并未弃用，无需盲目移除。

• 本地文件引用：可以直接保留，V2 完全支持。
• 远程文件引用：部分旧版远程引用方式可能受限，建议改为本地文件或仓库内引用。

V2 中extends正确用法示例：

services:
  web:
    extends:
      file: common.yml
      service: base-web

3. 跨文件配置复用

技术风险：YAML 锚点（&name和*name）仅在单个文件内有效，无法跨文件引用。原 V1 迁移指南中提到的跨文件锚点方案在 V2 中会导致部署失败。

推荐方案：

• 方案 A（推荐）：使用 Compose V2.20+ 引入的includes字段实现模块化。
• 方案 B：使用多文件组合启动，后加载的文件覆盖先加载的文件。

多文件组合启动示例：

docker compose -f base.yml -f override.yml up -d

怎么验证是否生效

执行以下命令检查迁移是否成功：

# 验证 V2 是否可用
docker compose version

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

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

# 检查服务状态
docker compose ps

如果docker compose config能正常输出解析后的配置且无警告，说明配置文件兼容 V2 语法。

常见坑

• 命令混用：有些脚本里写docker-compose，有些写docker compose，在 CI/CD 环境中容易因版本不一致导致构建失败
• version 字段警告：旧配置文件中的version: "3"在 V2 中会触发警告，建议移除
• scale 命令变化：V1 的docker-compose scale在 V2 中改为docker compose up `--scale`，注意参数前是双横线
• 扩展字段命名：自定义字段如果没有x-前缀，V2 可能报错而 V1 会静默忽略
• 插件安装位置：如果手动安装 V2 二进制，必须放在~/.docker/cli-plugins/目录，否则docker compose命令不可用
• 跨文件锚点失效：不要尝试在不同 YAML 文件间使用锚点引用，应改用includes或-f合并

参考来源

• Docker 官方文档 - Compose V2 迁移指南
• GitHub - docker/compose 项目 releases 页面
• Docker 官方博客 - Compose V2 General Availability