docker和compose版本不匹配导致编排失败，关键在于对齐docker引擎、compose工具及docker-compose.yml三者版本；需依次执行docker --version、docker-compose --version（或docker compose version）、cat docker-compose.yml | head -n 3查清现状，再按场景降级或升级，并用docker compose config校验语法、docker compose down -v清理残留后启动。
查清当前环境三要素
在终端依次运行以下命令，明确现状：
- docker --version → 查看 Docker 引擎版本（如 Docker version 20.10.24）
- docker-compose --version 或 docker compose version → 区分是 v1 还是 v2（v1 输出类似 docker-compose version 1.29.2；v2 输出类似 Docker Compose version v2.24.5）
- cat docker-compose.yml | head -n 3 → 确认文件开头是否有 version: '3.8' 或无 version（即 v1 格式）
按场景匹配降级或升级策略
不同组合需不同处理，不能一概而论：
- Docker 版本很旧（如 1.7.1 / 1.13.1） → 必须用 docker-compose v1.x（≤1.6.2） + v1 格式 yml（无 version 字段、无 services 块）
-
Docker ≥20.10，但用的是 docker-compose v1（如 1.29.2） → 推荐迁移到 docker compose（v2），命令改为
docker compose up，同时保留 yml 中version: '3.8' -
Docker 较新（≥24.x），但 yml 里写的是 version: '2' → 升级 yml 到
version: '3.9'或'3.10'，并检查是否误用了已废弃字段（如container_name在某些上下文中受限）
快速修复 yml 兼容性问题
当版本工具已匹配，但启动仍报“unsupported config option”，说明 yml 中用了当前版本不支持的语法。重点检查：
- depends_on：v1 不支持该字段；v2+ 支持，但仅控制启动顺序，不等待服务就绪
- volumes / networks 定义位置：v3 要求必须在文件末尾单独定义，不能只写在 service 下
-
build 参数嵌套：v3.8+ 支持
build: { context: ., dockerfile: Dockerfile.dev }；v2.x 只支持字符串或简单对象 - healthcheck / deploy / secrets：这些是 v3+ 特性，v1 完全不可用
验证与清理再启动
改完版本和配置后，不要直接 up，先做两步确认：
-
语法校验：运行
docker-compose config（v1）或docker compose config（v2）。若输出完整结构，说明 yml 无误；报错则按提示修正 -
清理残留状态：执行
docker-compose down -v（v1）或docker compose down -v（v2），清除旧网络、卷和容器，避免缓存干扰
最后再运行启动命令，问题通常即可解除。
