docker desktop 已识别 wsl2 但 docker run hello-world 失败，说明 wsl2 后端集成中断：需确认 wsl --list --verbose 中发行版状态为 running 且版本为 2，docker desktop 设置中已勾选对应发行版的 wsl 集成，并检查 /var/run/docker.sock 是否正确指向 /mnt/wsl/docker-desktop/distro/docker.sock。
docker info 显示 WSL 后端但 docker run hello-world 失败
这说明 Docker Desktop 已识别 WSL 2，但容器运行时链路中断。常见于 WSL 发行版未启用集成、或发行版本身卡在启动状态。
先检查 docker info 输出中是否含 Default Runtime: runc 和 Kernel Version: 5.15.133+（WSL2 内核版本），再确认 Platform: linux/amd64 —— 若是 linux/wsl2 或 windows，说明后端未真正切换。
- 运行
wsl --list --verbose，确保目标发行版（如Ubuntu）状态为Running且VERSION为2 - 在 Docker Desktop 设置 → Resources → WSL Integration 中，必须勾选对应发行版（不能只勾“Enable integration with my default WSL distro”）
- 若发行版刚升级过内核，执行
wsl --shutdown再重启该发行版，否则旧进程可能阻塞新 socket 连接
WSL 终端里 docker version 报错 “Cannot connect to the Docker daemon”
这是最典型的集成断连信号，本质是 WSL 环境没拿到 Docker Desktop 暴露的 Unix socket 路径。Docker Desktop 不会把 daemon 直接跑在 WSL 里，而是通过 /var/run/docker.sock 的符号链接转发到 Windows 主机侧的命名管道。
检查 /var/run/docker.sock 是否存在且为软链：ls -l /var/run/docker.sock。正常应指向 /mnt/wsl/docker-desktop/distro/docker.sock；若不存在或指向错误路径，说明集成未生效或 WSL 发行版未被正确注册。
- 确保该发行版已执行过一次
wsl -d <distro-name></distro-name>启动（仅安装不等于已初始化） - 关闭所有 WSL 实例：
wsl --shutdown，再打开 Docker Desktop 并等待右下角鲸鱼图标稳定（非“starting”闪烁态） - 不要手动修改
/etc/docker/daemon.json，Docker Desktop 会覆盖它；若已改过，删掉该文件并重启 WSL
wsl --list --verbose 卡住或超时返回 CommandTimedOut
这个超时不是 Docker 的问题，而是 WSL 自身服务异常。Docker Desktop 在启动时调用 wsl.exe 列发行版，一旦底层 wslexec 响应超时（默认 30 秒），整个集成流程就终止。
根本原因通常是 WSL 内核服务崩溃、发行版 ext4 虚拟磁盘损坏、或 Windows 安全功能（如 HVCI / Memory Integrity）与 WSL2 冲突。
- 以管理员身份运行 PowerShell，执行
wsl --update --install强制刷新内核和发行版元数据 - 禁用 Windows 安全中心里的 “Memory Integrity”（设置 → Windows Security → Device Security → Core Isolation → 关闭）
- 若某发行版长期卡死，用
wsl --unregister <distro-name></distro-name>彻底删除后重装，避免残留锁文件干扰
Docker Desktop 设置里找不到你的 WSL 发行版
不是 Docker Desktop 漏掉了，而是该发行版尚未完成首次初始化。WSL 发行版只有在第一次成功启动并完成用户账户配置后，才会被 Docker Desktop 扫描到。
例如：通过 Microsoft Store 安装 Ubuntu 后，必须手动运行一次 ubuntu（或 wsl -d Ubuntu），完成创建用户名/密码步骤，之后才能在 Docker Desktop 的 WSL Integration 列表中看到它。
- 若发行版名含空格或特殊字符（如
Ubuntu-24.04 LTS），Docker Desktop 可能无法识别；建议用wsl --rename改为纯字母名（如ubuntu24） - 检查
%USERPROFILE%\AppData\Local\Docker\wsl\data\目录是否存在且可读写；若被杀毒软件锁定，也会导致扫描失败 - 重启 Docker Desktop 前，务必先执行
wsl --shutdown，否则旧状态缓存可能持续干扰
wsl --list --verbose 是否秒出、docker info 是否显示 WSL2 作为运行平台、以及 docker run hello-world 是否真从 WSL 终端发起并成功退出。这三个环节里任意一个卡顿或报错，都意味着集成链路上有隐性断裂点，得顺着日志往 WSL 层深挖，而不是反复重启 Docker Desktop。
