如果 Windows 终端能运行 docker,但 Ubuntu 里提示 command not found,通常是该发行版没有启用 Docker Desktop 的 WSL 集成;如果命令存在却报 Cannot connect to the Docker daemon,应先检查 Docker Desktop 是否已启动、当前 Docker context 和 DOCKER_HOST。先用只读命令确定故障层,再按对应分支处理,不要一开始就重置 Docker 数据或注销 WSL 发行版。
本文适用于 Windows 上的 Docker Desktop、WSL 2 Linux 发行版和 Linux 容器工作流。Docker Desktop 的 WSL 2 后端、Docker VMM 与 Hyper-V 后端行为不同;先确认自己实际使用哪一种。Windows 容器模式也不等同于本文讨论的 Linux 容器环境。
先分清是 Windows、WSL 还是 Docker Engine 出错
先在 Windows PowerShell 中收集基本状态:
|
|
这些命令不修改容器或发行版。wsl --list --verbose 会显示每个发行版是 WSL 1 还是 WSL 2;docker version 的输出分为 Client 和 Server 两部分。只有 Client、没有 Server,说明 Docker CLI 已找到,但客户端没有成功连接到 Engine。
然后进入你实际开发使用的 Linux 发行版,再检查:
|
|
将两边结果放在一起看,可以避免把“Windows 找不到程序”“发行版没有注入 CLI”和“Engine 没有响应”混为一谈。后面的步骤都以这个判断为起点。
先确认 WSL 自己能正常运行
如果 wsl --status、wsl -l -v 或启动 Ubuntu 本身就报错,先处理 WSL 和 Windows 虚拟化组件,暂时不要改 Docker Desktop 设置。
Docker 官方当前列出的 Docker Desktop WSL 2 最低版本为 WSL 2.1.5,并建议保持 WSL 更新。查看本机版本:
|
|
如果 WSL 版本过旧,可以先保存正在编辑的文件,再更新并重启 WSL 虚拟机:
|
|
wsl --shutdown 会立即结束所有运行中的 WSL 发行版。再次启动 Ubuntu 后重查 wsl -l -v,确认目标发行版的 VERSION 列为 2。如果是 1,不要在未备份重要文件的情况下转换;转换需要时间,也可能失败。
WSL 更新命令失败时,可根据错误检查 Microsoft Store、Windows 更新和网络策略;wsl --update --web-download 可以改用网页下载路径。不要在更新中途强制关闭 Windows,也不要把 wsl --unregister 当作普通重启命令。
Docker Desktop 正在运行,且使用 Linux 容器模式
在 Windows 任务栏托盘确认 Docker Desktop 已完成启动。若状态仍是 Starting、Docker Engine is starting 或弹出引擎错误,先记录界面上的完整错误信息。托盘菜单里的“Switch to Linux containers”表示当前可能处于 Windows 容器模式;WSL Linux 容器开发需要切换到 Linux 容器。
WSL 集成选项只会在适用的后端和容器模式下出现。Docker Desktop 使用 WSL 2 engine 时,打开 Settings > General,检查 “Use the WSL 2 based engine”;再到 Settings > Resources > WSL Integration,为需要的发行版单独开启开关并选择 Apply。
如果机器装有多个发行版,默认发行版不一定是你打开的那个。用 wsl -l -v 查看实际名称,在集成页面启用正确的发行版。需要改变默认发行版时可运行:
|
|
将 Ubuntu 替换成列表中准确显示的名称。改变默认发行版只影响未指定发行版名称的 WSL 命令,不会把其他发行版转换为 WSL 2,也不会自动迁移文件。
WSL 里提示 docker 命令不存在
如果 Windows PowerShell 能运行 docker version,而 Linux 发行版返回 command not found,按下面顺序检查:
- 在
wsl -l -v中确认目标发行版的版本是 2。 - 在 Docker Desktop 设置中打开 WSL 2 engine。
- 在 Settings > Resources > WSL Integration 中启用当前发行版。
- 选择 Apply,等待 Docker Desktop 完成应用。
- 从 Windows 执行
wsl --shutdown,再重新打开该发行版。 - 在发行版中运行
command -v docker和docker version。
不要只因为命令不存在,就在发行版里再安装一套 Docker Engine。Docker 官方提示,在 WSL 发行版中直接安装 Docker Engine 或 Docker CLI,可能与 Docker Desktop 的集成冲突。双重安装还会让 Docker CLI 指向另一个 daemon,产生“Windows 上正常、Ubuntu 里容器列表不同”的情况。
如果你有意在 Linux 发行版内独立运行 Engine,那是另一种部署方式。应明确选择由谁管理 daemon、数据目录、开机服务和 Docker context;不要同时让两个 Engine 监听同一套开发命令,然后依靠碰运气决定连接目标。
命令存在,但提示无法连接 Docker daemon
先在 Windows 端检查 Docker Desktop 是否已完全启动,再运行:
|
|
如果当前 context 指向 SSH 主机或远端环境,docker 命令可能连的并不是本机 Desktop。确认后再切回 Desktop 对应的 context;不要盲目覆盖用户的 Docker 配置,因为远端 context 可能是刻意设置的。
在 WSL 中检查环境变量是否改写了连接地址:
|
|
DOCKER_HOST 可以强制 CLI 使用指定的 socket 或 TCP 地址;DOCKER_CONTEXT 也可能选择另一套 context。先记下变量值和来源,再决定是否在当前终端临时移除。PowerShell 可检查:
|
|
不要把 sudo docker 当作连接问题的通用修复方法。它可能改用 root 用户自己的 Docker 配置与 context,让你连接到不同的 daemon;权限错误需要先确认当前运行的是哪一个 Docker CLI 和 Engine。
如果 Docker Desktop 的 Engine 仍在启动,连续重试 Compose 命令只会重复失败。先在 Dashboard 确认引擎已就绪,再用 docker version 看到 Server 信息,最后运行项目命令。
命令能连上,但看到的容器和预期不同
这通常说明 CLI 连到了另一套 Engine,而不是容器“消失了”。先检查 docker context show,再检查环境变量和 CLI 的解析路径:
|
|
在 WSL 发行版中运行:
|
|
如果 type -a docker 列出多个路径,排查当前 shell 实际使用的第一个程序。Windows PATH 注入的 Docker Desktop CLI、发行版内自行安装的 CLI 和 shell alias 可能同时存在。先识别来源,不要直接删掉未知文件或改动系统 PATH。
容器、镜像和卷属于各自的 Docker Engine。切换 context 后,docker ps -a 或 docker volume ls 显示另一套结果是正常现象。准备清理某个 context 前,先确认当前 endpoint,避免把远端生产环境当成本机测试环境。
看到意外 WSL 错误或虚拟机启动失败
错误里如果包含 HCS_E_HYPERV_NOT_INSTALLED、ERROR_NOT_SUPPORTED,或者 wsl 命令本身也无法启动发行版,优先检查 Windows 功能和硬件虚拟化:
- BIOS/UEFI 中的 CPU 虚拟化功能是否开启。
- Windows 是否启用了 Virtual Machine Platform 和 Windows Subsystem for Linux。
- 虚拟机或云桌面内运行 Windows 时,宿主机是否启用了嵌套虚拟化。
- Hypervisor 是否被启动配置或其他虚拟化软件关闭。
- 最近是否安装过 Android 模拟器或旧版虚拟机软件并改变了 Hyper-V 设置。
在任务管理器的“性能 > CPU”页可以查看虚拟化状态。不要在不了解现有虚拟机配置时,直接修改 BCD 或 Windows 功能;企业设备也应先确认组织策略。
如果 wsl -l -v 正常,但只有 Docker Desktop 的 docker-desktop 发行版异常,保存错误全文和时间戳,并使用 Docker Desktop 的 Troubleshoot > Get support 收集诊断。不要手工删除 docker-desktop 或 docker-desktop-data 发行版,也不要在其中执行清理文件命令。
WSL 集成菜单缺失或选了发行版仍无效
先确认当前不是 Windows containers 模式,再确认 Docker Desktop 使用的是哪一种虚拟机后端。Docker 官方文档说明,完整 WSL Integration 仅适用于 WSL 2 engine;在 Docker VMM 模式下,近期版本可以从 WSL 发行版运行 Docker CLI,但它的 socket、直接挂载和开发工具支持边界不同。
切换后端之前,先阅读当前版本的 Docker Desktop 设置说明,并确认团队工具所需功能。VS Code Dev Containers、Docker SDK、Testcontainers 等依赖 Docker Engine API socket 的工具,不能仅凭 docker 命令可运行就假设全部兼容。
若你刚启用了集成但终端仍保留旧环境,执行一次:
|
|
再重新打开指定发行版。wsl --shutdown 会关闭所有发行版和 WSL 虚拟机;它不会重置文件,但未保存的 Linux 进程状态会丢失。
不要为了刷新集成而反复切换 WSL 1/2、注销发行版、执行 Docker Desktop Factory reset,或删除虚拟磁盘。这些操作可能造成数据丢失,且通常不是首轮排查所需。
Docker VMM 下命令能用,挂载或开发工具却不工作
Docker VMM 与 WSL 2 engine 的交互方式并不相同。在 VMM 模式下,WSL 可以通过 Windows interop 调用 Docker CLI;但当前文档列出的限制包括:没有 Linux Docker socket,且只能直接 bind mount Windows 驱动器中的文件。Docker SDK、Testcontainers 和 Dev Containers 等依赖 socket 的工具可能不能工作。
在 PowerShell 中启动的项目通常使用 C:\... 路径;从 WSL 启动时则会看到 /mnt/c/...。如果错误提示路径位于发行版内部的 /home/...,而你使用的是 Docker VMM,先按官方说明确认该工作流是否受支持。不要把 Linux 路径简单改写成 Windows 路径后假设权限、文件监控和性能都相同。
使用 WSL 2 engine 的 Linux 开发环境时,Docker 官方建议将项目代码放在 Linux 发行版的文件系统中,以减少跨 Windows 文件系统操作。若同一项目必须由 Windows 工具和 Linux 容器频繁读写,应评估文件权限、大小写、文件监听和挂载性能,再选定一个主要工作目录。
出现挂载失败时,先检查 Compose 中的源路径是否存在、当前命令从哪个目录执行、使用的是哪一种后端,以及目标发行版是否启用集成。避免把容器目录 /app、Windows 路径 C:\project 和 WSL 路径 /mnt/c/project 混成同一种路径。
WSL 有发行版,Docker Desktop 却找不到它
从 Windows 重新列出发行版并检查版本列:
|
|
如果发行版名称含空格或大小写不同,按命令输出中的原名在集成设置里选择。新安装的发行版可能默认使用 WSL 1;只有 WSL 2 发行版才能用于 Docker Desktop 的 WSL 2 集成。转换之前先备份:
|
|
导出文件包含发行版数据,可能占用大量空间。确认备份确实生成且可访问后,再进行转换;不要把示例名称直接用于含有不同数据的重要发行版。
如果之前重命名、迁移或导入过发行版,先用 wsl -l -v 确认注册名称和状态,不要通过删除注册项来“重新发现”它。发行版注册信息、磁盘文件和 Docker Desktop 管理的虚拟磁盘是不同对象。
Docker Desktop 更新后集成突然失效
更新后不要立刻清除所有镜像和容器。先记录 Docker Desktop 版本、wsl --version、发行版名称、后端模式和完整报错,再查看 Docker 官方 release notes 是否提到相同版本组合。
Docker 的近期发行说明记录过 WSL 2.6.x 及更高版本下,用户发行版集成出现零字节代理程序,导致 Permission denied 或 Exec format error 的问题,并说明某个后续版本已修复。若错误文本与此相符,先核对实际 Docker Desktop 版本和升级渠道;不要直接复制网上流传的手动替换内部文件步骤。
同一份发行说明也记录过 Resource Saver 停止虚拟机后,已集成发行版中的 Docker CLI 暂时无法工作的修复。问题是否适用于你的机器取决于实际版本,不要只根据关键词判断。保留诊断 ID 和可复现步骤比猜测版本更有用。
可以把复现步骤缩到最小:完全退出 Docker Desktop,运行 wsl --shutdown,重新启动 Docker Desktop,等待 Engine 就绪后只启动一个目标发行版,再运行 docker version。记录每一步的时间和输出。如果只有某一个发行版失败,就聚焦那个发行版;如果所有 WSL 命令都失败,则回到 WSL 和 Windows 功能检查。
排查时一次只改一个设置,例如先更新 WSL、验证后再切换 Docker Desktop 后端。连续更新 WSL、切换 Hyper-V/VMM、重置数据并重装会抹掉故障出现的因果线索,也可能引入新的变量。
如果怀疑升级回归,先核对 Docker Desktop 的 About 页面与官方 release notes 中的版本日期,再决定是否按组织政策升级或回退。不要下载来源不明的旧安装包,也不要从论坛复制内部 docker-desktop 文件覆盖脚本。
拉取镜像失败不一定是 WSL 集成故障
如果 docker version 已显示正常的 Server,但 docker pull 报 DNS、代理、TLS 或认证错误,CLI 通常已经连接到 Engine。此时应检查 Windows 网络、Docker Desktop 代理、镜像仓库凭据和当前 registry 地址,而不是重复开关 WSL 集成。
可以先运行一个不拉取新镜像的状态检查,并记录失败命令的完整错误文本。若错误只发生在公司网络或 VPN 开启时,比较同一网络条件下的 DNS、代理策略和企业证书要求;不要为了验证而关闭公司安全代理或绕过证书校验。
docker compose up 失败也可能是项目配置或容器应用问题。可先单独执行 docker compose config 检查 Compose 展开结果,再确认错误发生在镜像拉取、容器创建、卷挂载还是应用启动阶段。只有命令连接 daemon 失败时,才继续走本文的 WSL 集成分支。
如果 Engine 已连接,但 Compose 环境变量没有进入容器,可继续看Docker Compose 环境变量排查指南;如果问题是数据库尚未就绪或服务启动顺序,请看Compose depends_on 与 healthcheck 指南。
磁盘空间、重置和备份边界
Docker Desktop 的 WSL 2 引擎数据通常保存在用户目录下的 Docker WSL 数据位置,但具体位置可能被设置修改。删除该虚拟磁盘可能永久删除本机镜像、容器和卷数据;Clean up data 与 Reset to factory defaults 也不是无损的普通重启选项。
在执行任何清理之前,先确认需要保留的数据库卷、镜像和容器数据是否已有独立备份。容器可重建不代表 volume 中的数据也可重建。企业环境中,先检查数据保留和备份策略。
优先使用 Docker Desktop 提供的诊断、正常退出和重启流程。只有明确理解清理范围并已验证备份后,再考虑清空数据或恢复出厂设置。
收集诊断信息并验证修复
当 Docker Dashboard 可以打开时,在 Troubleshoot 菜单选择 Get support,等诊断收集完成后上传并保存 Diagnostic ID。若界面无法启动,可根据安装方式运行官方的 docker desktop diagnose 命令;命令行工具是否已安装取决于 Docker Desktop 版本。
提交问题时附上以下信息,避免只写“Docker 坏了”:
- Windows 版本与 Docker Desktop 版本。
wsl --version、wsl --status和wsl -l -v输出。- 目标发行版名称、WSL 版本以及使用的 Docker Desktop 后端。
- 在 PowerShell 和 WSL 分别运行
docker version的完整结果。 docker context show输出,以及是否设置了DOCKER_HOST/DOCKER_CONTEXT。- 完整错误文本、首次出现时间、更新前后是否变化和 Diagnostic ID。
修复后分别在 PowerShell 和目标 WSL 发行版中验证:
|
|
|
|
只有两个终端都连接到预期的本地 Engine,且 docker version 显示 Client 与 Server 信息,才算完成这次集成验证。随后再运行真实项目的 docker compose config 和启动命令,确认实际挂载、网络与环境变量符合预期。
常见问题
Windows 里 Docker 正常,Ubuntu 里没有 docker 命令,应该重装吗?
先启用 Docker Desktop 的 WSL 2 engine 和 Ubuntu 集成,再关闭并重新打开 WSL。不要先在 Ubuntu 中安装第二套 Docker Engine。
docker version 只显示 Client,代表什么?
CLI 已经运行,但没有取得 Engine Server 响应。检查 Docker Desktop 启动状态、当前 context、DOCKER_HOST 和后端模式。
运行 wsl --shutdown 会删掉容器吗?
它会停止所有 WSL 发行版和 WSL 虚拟机,不是用于删除数据的命令。不过在运行中的程序里未保存的状态会中断;停止后再启动 Docker Desktop 与目标发行版进行验证。
可以删除 docker-desktop-data 来修复启动吗?
不要把删除内部发行版当作普通修复操作。这可能清空本机镜像、容器或卷。先收集诊断信息并核对官方恢复步骤,确认备份后才考虑数据级操作。
为什么 WSL 里能运行 docker,但 Dev Containers 或 Testcontainers 失败?
命令可运行不等于 Docker socket 和 Engine API 的所有使用方式都可用。先确认 Docker Desktop 后端;Docker VMM 模式有独立的 socket 和挂载限制。
官方资料
- Docker Desktop WSL 2 后端:WSL 版本要求、集成设置、Docker VMM 边界。
- Docker Desktop 常见故障主题:虚拟化错误和 WSL 启动故障。
- Docker Desktop 故障排查与诊断:诊断 ID、日志与支持流程。
- Docker Desktop 发行说明:核对特定版本是否修复 WSL 集成问题。
- Microsoft WSL 基本命令:更新、检查、关闭和导出发行版。