版本不匹配怎么发生
Docker 客户端与 daemon 之间通过带版本号的 REST API 通信：每次发布，客户端都可能支持一个更新的版本号，daemon 则同时支持一段范围内的版本。Docker CLI 自身会做版本协商，通常自动降到 daemon 支持的最高版本，所以直接敲 docker ps 很少碰到这类报错。报错更多出现在固定了版本的调用方——直接 curl REST 接口的脚本、写死版本号的 SDK，或环境里设置了 DOCKER_API_VERSION。
基本信息
| 典型报错 | client version 1.xx is too new，或 too old for API version |
|---|---|
| 核对两端 | docker version 输出的 Client 与 Server APIVersion |
| 临时兼容 | DOCKER_API_VERSION=1.41 docker ps |
| 直接调 API | curl --unix-socket /var/run/docker.sock 并手写版本路径 |
| 常见来源 | 老 CLI 连新 daemon、新 CLI 连远端旧 daemon、固定版本的 SDK |
| 副作用 | 锁定版本会同时锁住该版本之后新增的接口与字段 |
| 适用范围 | Linux/Windows 客户端与 daemon 通用，跨版本组网时尤其常见 |
典型使用场景
- 运维机上装的是较老的 docker CLI，连内网较新的 daemon
- CI 镜像里打包的客户端版本陈旧，连生产 daemon 时报 too old
- 自写脚本直接用 curl 调固定版本路径的接口
- 自研 SDK 或编排工具把 API 版本号写在代码里
- daemon 升级后老脚本突然失败，需要先判断是不是版本问题
核对与应急
核对与应急
docker version --format 'client={{.Client.APIVersion}} server={{.Server.APIVersion}}' # 两端版本对照
docker version # 完整输出，daemon 会报告它支持的最低版本
DOCKER_API_VERSION=1.41 docker ps # 临时把客户端钉到指定版本
env | grep DOCKER_ # 排查是否有人把版本写进了环境变量
curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containers/json # 直接调 REST 时路径带版本
docker info --format '{{.ServerVersion}}' # 确认 daemon 版本，规划升级窗口报错方向与处理
| 报错表现 | 成因 | 处理方向 |
|---|---|---|
| client version too new | 客户端要求的版本高于 daemon 支持的上限 | 升级 daemon，或临时用 DOCKER_API_VERSION 降级 |
| client version too old | daemon 已不再支持这么老的客户端版本 | 升级客户端，这是唯一正解 |
| 固定版本路径返回 400 或 404 | daemon 已移除该版本的路由 | 改成先协商再拼路径，不要写死版本号 |
| SDK 反序列化报错 | 版本过老，响应里缺少新字段 | 对齐 SDK 与 daemon 的版本 |
| 只在某台机器复现 | 该机器的客户端或环境变量不同 | 用 docker version 逐台对比 |
DOCKER_API_VERSION 会覆盖协商行为，让客户端固定使用指定版本，只适合应急。长期依赖它意味着拿不到新版本才有的接口与字段，也会掩盖真正需要做的升级。
通过 DOCKER_HOST 或 docker context 连远端 daemon 时，报错来自对端版本，容易误判成本机环境问题。排查前先确认这条命令实际连的是哪个 daemon。
把 DOCKER_API_VERSION 写进 CI 或镜像的常驻配置，会让所有人看不到版本差异，等真正需要新功能时故障集中爆发。它只应作为临时兼容手段，并且约定一个移除期限。