如何通过 version 关键字在 Docker Compose 中锁定配置规范教程

必须指定version字段，因其强制定义配置规范版本并决定语法功能边界：v2不支持deploy，v3引入secrets等生产特性，v3.8为2026年推荐版；需匹配Docker Engine与Compose CLI版本，且值须加引号避免浮点解析错误。

直接在 docker-compose.yml 文件开头写明 version 字段，就能锁定所用的配置规范版本。这不是可选项，而是强制要求——没有它，Compose 会报错拒绝运行。

为什么必须指定 version

不同 version 对应不同的语法支持和功能边界。比如：

• version: '2' 支持自定义网络和卷，但不支持 deploy 段（无法用于 Swarm）
• version: '3' 引入 deploy、secrets、configs 等生产级字段，但要求 Docker Engine ≥ 1.13
• version: '3.8' 是当前稳定推荐版本（截至 2026 年），兼容 Compose V2 CLI，支持健康检查、资源限制、扩展性更强

怎么选对 version 值

不是越高越好，要匹配你的 Docker 和 Compose 环境：

• 先查本地版本：docker --version 和 docker-compose version
• Docker Engine ≥ 20.10 + Compose CLI ≥ 2.0 → 推荐 version: '3.8'
• 若用旧版 Docker（如 18.x）且无法升级，version: '3.3' 或 '3.7' 更稳妥
• 避免用 latest 或留空 —— Compose 不识别动态版本，也不做自动降级

常见写法与注意事项

写法必须严格，YAML 对格式敏感：

• 必须是文件第一行（允许前面有注释，但 version 要顶格）
• 值要用引号包裹，如 version: '3.8' 或 version: "3.8"，不能写成 version: 3.8（会被解析为浮点数，导致错误）
• 不要混用版本特性：比如在 version: '2' 下写 deploy: 字段，会直接报错“unsupported config option”
• 官方已不再维护 v1 和 v2 的独立文档，所有新功能只在 v3+ 规范中更新

验证是否生效

改完 version 后，运行以下命令快速验证：

• docker-compose config —— 解析并输出规范化后的配置，成功即说明 version 兼容
• docker-compose config --quiet —— 静默模式，仅返回错误，适合 CI/CD 中做校验
• 启动时若报 version is unsupported，说明本地 Compose 版本太低，需升级 CLI