构建器连接失败主因是WSL2运行时未就绪或Docker Desktop专用发行版异常；需检查wsl -l -v中docker-desktop状态是否Running，确认Docker Desktop启用WSL2引擎及集成，排查com.docker.service服务是否卡在START_PENDING，并验证/docker.sock路径连通性。
构建器连接失败，基本不是构建器本身坏了，而是它依赖的 WSL2 运行时没就绪，或者 Docker Desktop 的专用发行版状态异常。
wsl -l -v 显示 docker-desktop 状态不是 Running
这是最常见也最容易被忽略的起点。Docker Desktop 启动后会在 WSL2 里注册两个（或一个）专用发行版：docker-desktop 和 docker-desktop-data（新版本可能只用前者）。如果它们没起来，构建器根本连不到引擎。
- 在 PowerShell 或 CMD 中运行
wsl -l -v，确认这两项是否存在，且状态是Running；如果显示Stopped或压根不出现，说明 WSL 层初始化失败 - 尝试手动启动：
wsl -d docker-desktop—— 如果卡住或报CommandTimedOut，问题出在 WSL 服务或虚拟磁盘上 - 不要直接删发行版，先执行
wsl --shutdown再重试；若仍无效，再考虑导出+注销+重导入 - 注意：
wsl --update只更新内核，不修复已损坏的ext4.vhdx文件；磁盘损坏时，wsl --shutdown后重启可能仍无法恢复状态
Docker Desktop 设置里 WSL 集成开关关闭或灰显
即使 WSL2 功能开了、发行版也存在，Docker Desktop 自己可能没启用 WSL 集成——这会导致构建器走不到 WSL 后端，转而尝试 fallback 到已弃用的 Hyper-V 路径，最终连接超时。
- 打开 Docker Desktop → Settings → General → 确认
Use the WSL 2 based engine已勾选 - 再进 Settings → Resources → WSL Integration → 检查
Enable integration with my default WSL distro是否开启；若灰显，说明默认发行版未设置或未运行，需先在 PowerShell 执行wsl --set-default Ubuntu（替换成你实际安装的发行版名） - 修改后必须点击
Apply & Restart，仅重启 Docker Desktop 不生效 - 某些旧版 Docker Desktop 在 WSL 发行版未运行时会静默禁用该开关，而不是报错，容易误判为“设置已生效”
构建日志里反复出现 dial unix /run/docker.sock: connect: no such file or directory
这个错误看似是 socket 文件丢了，实则是 Docker 引擎根本没在 WSL 里跑起来。WSL 中的 dockerd 进程由 docker-desktop 发行版自动拉起，一旦该发行版启动失败，socket 就永远不会创建。
- 不要去 WSL 里手动运行
sudo dockerd—— 这会和 Docker Desktop 自带的引擎冲突，且无法接入其网络/存储管理 - 进入
wsl -d docker-desktop后，检查ps aux | grep dockerd是否有进程；若无，看/var/log/docker.log或journalctl -u docker（取决于发行版）是否有初始化失败记录 - 常见根因：WSL2 分区磁盘空间不足（尤其
docker-desktop-data的ext4.vhdx占满）、/etc/wsl.conf里配置了非法挂载路径、或 Windows 防火墙/杀软拦截了wslservice.exe - 临时验证方式：在 WSL 里执行
curl --unix-socket /var/run/docker.sock http://localhost/version，能返回 JSON 才算真正通了
Windows 服务 com.docker.service 处于 START_PENDING 状态
这个服务是 Docker Desktop 的主机侧协调器，负责与 WSL 通信、转发构建请求。它卡在 START_PENDING，意味着整个构建链路从第一步就堵死了。
- 用管理员权限运行 PowerShell，执行
sc query com.docker.service，确认状态；若为START_PENDING，等 2 分钟再查一次，仍未变则需干预 - 先停掉所有 WSL 相关服务：
net stop LxssManager（旧版）或net stop WSLService（新版），再net start WSLService - 若服务启动失败，查事件查看器 → Windows 日志 → System，筛选来源为
Service Control Manager，找对应时间戳的错误事件，常伴随0x80070570或1603 - 别跳过系统重启 —— 很多时候
START_PENDING是因为 WSL2 内核模块未正确加载，仅wsl --shutdown不够，必须冷重启让 NT 内核重新初始化虚拟化栈
真正卡住构建器的，往往不是 docker build 命令本身，而是它背后那条从 Windows 服务 → WSLService → docker-desktop 发行版 → dockerd 的四层调用链里，某一层没完成 handshake。每层都有自己的健康信号，漏看任意一个，排查就会绕远路。
