Windows Docker环境搭建：从WSL虚拟化到Docker Desktop配置全指南

1. 先搞清楚 WSL 和 Docker Desktop 的关系别急着装如果你在 Windows 上想用 Docker大概率会搜到 WSLWindows Subsystem for Linux。很多人第一步就卡住了因为没理清它们之间的关系。简单说WSL 不是 Docker它是一个让你在 Windows 里原生运行 Linux 环境的子系统。而 Docker Desktop for Windows 是一个桌面应用它可以选择使用 WSL 2 作为后端引擎来运行容器。为什么要先搞懂这个因为你的安装路径和后续问题的排查方向完全取决于这个选择。如果你直接在 Windows 的命令提示符或 PowerShell 里运行docker命令是不会有任何结果的。Docker 的核心是 Linux 内核的特性所以它需要一个 Linux 环境。传统方式是装一个虚拟机如 VMware但 WSL 2 提供了更轻量、集成度更高的方案。所以整个流程的逻辑链条是启用 Windows 的虚拟化功能 - 安装 WSL - 将 WSL 2 设置为默认版本 - 安装一个 Linux 发行版如 Ubuntu- 最后安装 Docker Desktop 并配置其使用 WSL 2 后端。很多人遇到的virtualization support not detected或Docker Desktop failed to start这类错误八成问题出在最开始的虚拟化或 WSL 环节而不是 Docker Desktop 本身。下面我就按这个从底层到应用的顺序把安装、基本操作、系统迁移和清理卸载一次性讲透。2. 安装准备虚拟化、WSL 与 Linux 发行版安装不是无脑点下一步尤其是对于开发环境前置条件没满足后面会有一堆莫名奇妙的错误。我建议你按这个顺序检查并操作。2.1 确认并启用虚拟化这是所有步骤的基石。WSL 2 和 Docker 都需要 CPU 的硬件虚拟化支持Intel VT-x 或 AMD-V。如何检查是否已启用打开任务管理器CtrlShiftEsc。切换到“性能”标签页。看“CPU”部分如果“虚拟化”显示为“已启用”那这一步就过了。如果显示“已禁用”就需要进 BIOS/UEFI 开启。如何在 BIOS/UEFI 中开启这个因电脑品牌Dell, HP, Lenovo, ASUS 等而异没有统一路径。通用方法是重启电脑在开机自检画面时快速连续按指定键进入 BIOS/UEFI 设置界面通常是 F2、F10、F12、Del 或 Esc。在设置界面中找到类似Virtualization Technology、Intel VT-x、AMD-V、SVM Mode的选项。将其状态从Disabled改为Enabled。保存并退出通常是 F10电脑会自动重启。注意有些电脑特别是某些品牌笔记本可能在 BIOS 里还藏着一个“虚拟机监控程序”或“Hyper-V”相关的开关如果后续步骤仍报虚拟化错误可以一并检查开启。2.2 安装 WSL 并升级到 WSL 2Windows 10 2004 及以上版本和 Windows 11 都内置了 WSL 安装命令。这是目前最推荐的方式。一键安装推荐 以管理员身份打开 PowerShell 或 Windows 终端输入以下命令wsl --install这个命令会默认执行以下几件事启用“适用于 Linux 的 Windows 子系统”可选功能。启用“虚拟机平台”可选功能。下载并安装最新的 Linux 内核更新包。将 WSL 2 设置为默认版本。下载并安装默认的 Linux 发行版通常是 Ubuntu。执行后需要重启电脑。重启后会自动弹出窗口开始设置 Ubuntu让你创建用户名和密码。手动分步安装用于排查或定制 如果wsl --install执行太慢或出错可以手动分步进行这样能看清哪一步出了问题。# 1. 启用 WSL 功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 2. 启用虚拟机平台功能 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 3. 重启电脑 # 重启后继续以下步骤 # 4. 下载并安装 WSL 2 Linux 内核更新包 # 需要去微软官网下载安装包安装后继续。 # 5. 设置 WSL 2 为默认版本 wsl --set-default-version 2验证 WSL 安装 安装并设置好 Linux 发行版后在 PowerShell 中运行wsl --list --verbose # 或简写为 wsl -l -v你会看到类似下面的输出确认发行版名称和它运行的 WSL 版本应该是 2。NAME STATE VERSION * Ubuntu Running 22.3 安装 Docker Desktop 并连接 WSL 2下载去 Docker 官网下载 Docker Desktop for Windows 的安装包。安装运行安装包安装过程中确保勾选以下两个选项Install required Windows components for WSL 2为 WSL 2 安装必需的 Windows 组件。Add shortcut to desktop按需选择。配置安装完成后启动 Docker Desktop。第一次启动可能较慢。进入设置SettingsGeneral确认Start Docker Desktop when you log in等选项按需勾选。Resources-WSL Integration这是关键你会看到已安装的 WSL 发行版列表如 Ubuntu。将你想要集成 Docker 的发行版右侧的开关打开。这步操作意味着 Docker 命令和守护进程将在这个 WSL 发行版中运行。验证打开之前安装的 Ubuntu 终端可以在开始菜单里找或 PowerShell 里输入wsl进入输入docker --version docker run hello-world如果能看到 Docker 版本信息并且hello-world容器能成功运行并输出欢迎信息那么恭喜你整个环境就打通了。3. WSL 的基本操作与 Docker 日常使用环境搭好之后日常开发就在 WSL 的 Linux 终端里进行。这里列出最常用的一些操作。3.1 WSL 常用命令这些命令在 Windows 的 PowerShell 或 CMD 中执行用于管理 WSL 本身。wsl -l -v列出所有已安装的发行版及其状态和 WSL 版本。wsl默认进入默认的 WSL 发行版。wsl -d 发行版名称进入指定的 WSL 发行版。wsl --shutdown立即终止所有正在运行的 WSL 发行版和虚拟机。这在 Docker Desktop 卡住或资源占用异常时很有用相当于强制重启 WSL 后端。wsl --terminate 发行版名称终止指定的发行版。wsl --export 发行版名称 导出文件路径.tar导出发行版用于备份或迁移。wsl --import 新发行版名称 安装位置 导入文件路径.tar导入发行版。wsl --set-version 发行版名称 版本号切换指定发行版的 WSL 版本1 或 2。wsl --set-default-version 版本号设置新安装发行版的默认版本。3.2 在 WSL 中使用 Docker一旦 Docker Desktop 的 WSL 集成开启你在 WSL 终端里的体验就和在原生 Linux 上几乎一样。文件系统互访在 WSL 中你可以通过/mnt/c/、/mnt/d/等路径直接访问 Windows 的 C 盘、D 盘。在 Windows 中可以通过\\wsl$\发行版名称的网络路径访问 WSL 的文件系统。例如在文件资源管理器地址栏输入\\wsl$\Ubuntu即可。运行容器所有docker run、docker build、docker-compose up等命令都在 WSL 终端内执行。持久化数据对于数据库等需要持久化的数据强烈建议使用 Docker 卷volume或绑定挂载bind mount到 WSL 内部的文件路径而不是/mnt/c/下的 Windows 路径因为跨文件系统性能损耗很大。# 推荐使用 Docker 卷 docker run -v my_volume:/var/lib/mysql mysql # 或绑定挂载到 WSL 家目录 docker run -v ~/my_project/data:/app/data my_image # 不推荐直接挂载 Windows 盘符性能差权限问题多 # docker run -v /mnt/c/Users/xxx/data:/app/data my_image4. 导出、导入与迁移备份你的开发环境这是 WSL 非常实用的功能可以把配置好的整个 Linux 环境包括安装的软件、Docker 镜像、项目文件打包带走或者复制一份干净的出来。4.1 导出 WSL 发行版假设你的发行版叫Ubuntu你想把它备份到 D 盘。首先在 PowerShell 中关闭该发行版wsl --terminate Ubuntu执行导出命令wsl --export Ubuntu D:\wsl_backup\ubuntu_backup.tar这个过程会将整个发行版文件系统打包成一个tar文件。文件大小可能有好几个 GB时间也会比较长。4.2 导入 WSL 发行版你可以把导出的tar文件导入为一个新的发行版。这常用于环境克隆或迁移到新电脑。# 在 PowerShell 中执行 wsl --import Ubuntu_New D:\wsl_instances\ubuntu_new D:\wsl_backup\ubuntu_backup.tarUbuntu_New新发行版的名称不能和已有的重复。D:\wsl_instances\ubuntu_new新发行版的虚拟硬盘文件将要存放的Windows 路径目录。这个目录需要提前创建好。最后是备份文件的路径。导入完成后使用wsl -d Ubuntu_New即可进入。注意导入的发行版默认用户是root如果你需要之前配置的普通用户需要修改 WSL 配置。4.3 迁移 WSL 发行版到其他驱动器如果你的 C 盘空间告急可以将 WSL 发行版迁移到 D 盘等空间更大的驱动器。导出发行版如上所述。注销卸载原有的发行版wsl --unregister Ubuntu将导出的tar文件导入到新的目标驱动器路径如上所述。注意wsl --import导入时指定的安装位置是虚拟磁盘文件ext4.vhdx的存放目录这个文件会随着你使用而增长。确保目标驱动器有足够空间。5. 删除与卸载如何干净地移除当你需要彻底清理时顺序很重要乱删可能会在系统里留下残骸。5.1 卸载 Docker Desktop这是最直接的一步。通过 Windows 的“应用和功能”设置找到Docker Desktop点击卸载。卸载程序通常会处理得比较干净。卸载后建议重启一次电脑。5.2 注销卸载WSL 发行版如果你不想再用某个 Linux 发行版了可以注销它。这会删除该发行版内的所有数据包括你的个人文件、安装的软件和 Docker 存储在其中的镜像、容器操作前请确保已备份。wsl --unregister Ubuntu将Ubuntu替换为你的发行版名称。执行后该发行版将从列表中消失其占用的磁盘空间会被释放。5.3 完全关闭并移除 WSL 功能如果你确定不再需要任何 WSL 环境可以将其作为 Windows 功能关闭。在 PowerShell 中关闭所有 WSLwsl --shutdown打开“控制面板” - “程序” - “启用或关闭 Windows 功能”。取消勾选以下两项“适用于 Linux 的 Windows 子系统”“虚拟机平台”点击确定根据提示重启电脑。重启后WSL 功能就被移除了。你可以手动删除之前存放 WSL 虚拟磁盘文件的目录例如%LOCALAPPDATA%\Packages\CanonicalGroupLimited*或你自己指定的导入目录来彻底清理空间。6. 常见问题与排查思路按照上面的流程走大部分问题都能避免。但如果遇到问题可以按这个顺序排查。问题Docker Desktop failed to start because virtualisation support wasn’t detected.排查这是最经典的错误。100% 是虚拟化问题。回到2.1节确认 BIOS/UEFI 中虚拟化已开启。确保没有其他虚拟化软件如某些老版本 Android 模拟器、旧版 VirtualBox冲突暂时关闭它们。在“启用或关闭 Windows 功能”中确认“Hyper-V”和“Windows 虚拟机监控程序平台”已勾选Docker Desktop 安装器通常会帮你勾选。问题WSL: 检测到 localhost 代理配置但未镜像到 WSL。NAT 模式下的 WSL 不支持 localhost...排查这是网络代理问题。如果你在 Windows 上设置了系统代理如某些网络工具WSL 2 默认不会自动继承。方案一推荐在 WSL 的 Linux 终端内手动设置HTTP_PROXY和HTTPS_PROXY环境变量指向 Windows 主机的 IP通常是host.docker.internal或127.0.0.1和端口。方案二在 Docker Desktop 设置中找到Resources-Network可以尝试修改 DNS 或关闭Experimental Features中的某些网络特性。问题WSL --install 太慢或安装卡住排查这通常是网络问题因为需要从微软服务器下载 Linux 内核和发行版。换源对于wsl --install安装的默认 Ubuntu安装完成后在 Ubuntu 终端内执行sudo sed -i ‘s//archive.ubuntu.com//mirrors.aliyun.comg’ /etc/apt/sources.list更换阿里云镜像源然后sudo apt update。手动下载直接去微软商店搜索 “Ubuntu” 等发行版并安装有时比命令行更快。安装后仍需确保 WSL 版本是 2。问题Docker 命令在 WSL 中报错 “Cannot connect to the Docker daemon”排查首先确认 Docker Desktop 是否正在运行Windows 任务栏右下角应有 Docker 图标。确认在 Docker Desktop 设置的Resources-WSL Integration中对应的 WSL 发行版开关已打开。在 PowerShell 中执行wsl --shutdown然后重新启动 Docker Desktop 和 WSL 终端。问题文件操作在/mnt/c/下异常慢排查这是预期行为。WSL 2 访问 Windows 文件系统/mnt/是通过网络桥接性能有损失。最佳实践将项目代码放在 WSL 内部的文件系统里如~/project。可以用git clone直接克隆到 WSL 内部。如果需要用 Windows 编辑器如 VSCode可以安装 “Remote - WSL” 扩展它会自动处理文件路径让你在 Windows 下编辑 WSL 里的文件体验无缝。我个人更建议在 Windows 上用 Docker就彻底拥抱 WSL 2 这个 Linux 环境。把开发、构建、测试的上下文都放在 WSL 内部只把 Docker Desktop 当作一个管理和服务后台。这样能避开绝大多数因文件系统和路径差异导致的诡异问题。当环境配置好后定期用wsl --export做个备份会是成本最低的“后悔药”。