docker 命令报 Cannot connect to the Docker daemon at unix:///var/run/docker.sock / failed to connect to the docker API（连不上 daemon）

症状

`docker ps` / `docker run` 等命令一执行就报连不上 daemon，两种文案（版本不同）：

```

# 老版 CLI 文案

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

# 新版 CLI 文案（docker 25+）

failed to connect to the docker API at unix:///tmp/no-such.sock; check if the path is correct

and if the daemon is running: dial unix /tmp/no-such.sock: connect: no such file or directory

```

特征：**CLI 能跑、报错的是连接**（不是 command not found）；报错里的路径是关键线索——指向 `/var/run/docker.sock`（默认）还是别处（说明被 DOCKER_HOST/context 改过）；WSL 里装过 Docker Desktop 又用原生 docker 的机器最容易出现。

原因

docker CLI 通过 unix socket 与 daemon 通信（默认 `/var/run/docker.sock`）。连不上的三大根因：

1. **daemon 没在跑**：原生 docker 需 `systemctl start docker`（或 `sudo service docker start`）；Docker Desktop 需启动应用/WSL 集成；

2. **socket 路径不对**：`DOCKER_HOST` 环境变量或 `docker context` 指向了不存在的 socket——WSL 里最常见：环境里残留 `DOCKER_HOST=unix:///mnt/wsl/docker-desktop/shared-sockets/.../docker.proxy.sock`（Docker Desktop 路径），但实际用原生 daemon；或 Desktop 升级后 socket 路径变化；

3. **权限不足**：socket 属主 root:docker（`srw-rw----`），非 root 用户不在 docker 组时 `permission denied`（报错是 connect: permission denied）。

解法

1. **看报错里的路径**：如果路径不是 `/var/run/docker.sock`，先查环境变量：`env | grep -i docker_host`——有就 `unset DOCKER_HOST`（或 `export -n DOCKER_HOST`）再试。

2. **看 context**：`docker context ls`，看当前 `*` 的 endpoint 是什么；误配就 `docker context use default`。

3. **确认 socket 与 daemon**：`ls -l /var/run/docker.sock` 不存在 = daemon 没起（`sudo systemctl start docker` / `sudo service docker start`）；存在但报 permission denied = 用户不在 docker 组（`sudo usermod -aG docker $USER` 后重新登录，或临时 `sudo docker ...`）。

4. **WSL + Docker Desktop 混用**：二选一——用 Desktop 就保持 `DOCKER_HOST` 指向它的 socket（或用 `docker context use desktop-linux`）；用原生 daemon 就清掉 Desktop 相关环境变量/context，别让两个入口打架。

5. **验证**：`docker ps` 正常返回即恢复。

验证证据

- 本地实测（2026-08-29，WSL Ubuntu，docker CLI 29.1.3 / daemon 29.1.3）：

- 基线：`/var/run/docker.sock` 存在（srw-rw---- root docker），docker ps 正常；

- 复现 1：`DOCKER_HOST=unix:///tmp/no-such-docker.sock docker ps` → `failed to connect to the docker API at unix:///tmp/no-such-docker.sock ... dial unix ... no such file or directory`（exit 1）；

- 复现 1b：`DOCKER_HOST` 指向 Docker Desktop 的 socket 路径（本机真实残留值 `/mnt/wsl/docker-desktop/shared-sockets/guest-services/docker.proxy.sock`）→ 该文件不存在 → 同样报错——即本机此前「docker 全挂」的真实原因；

- 排查：`docker context ls` 显示 default（unix:///var/run/docker.sock）与 desktop-linux 两个 context；`env | grep -i DOCKER_HOST` 定位污染源；

- 修复：unset DOCKER_HOST 后 docker ps 恢复（daemon 其实一直在跑）。

- 实测复现日志（2026-08-29）