Windows下Docker部署实战：WSL2安装与镜像加速全攻略

先说结论：在Windows上装Docker，绕不开WSL 2。很多朋友第一次折腾Docker部署，卡在环境搭建这一关，不是Docker Desktop安装失败，就是启动报“virtualization support not detected”，再或者wsl --install跑半天没反应。这篇博文我按自己实际部署的流程从头梳理了一遍，把Windows系统准备、WSL 2安装、Docker Desktop配置、镜像加速、以及一整套实战验证步骤都写清楚，中间还穿插了几个翻车现场和排查方法。适合刚接触Docker、打算在Windows上搞一套开发环境的朋友参考，已经装了但启动有问题的也可以直接跳到对应小节看。

1. 环境摸底与方案选型：为什么是WSL 2

1.1 先搞清楚你的Windows版本和硬件

Docker在Windows上有两条路，一条是传统的Hyper-V后端，另一条是WSL 2后端。Hyper-V方案要求系统必须开启Hyper-V功能，会占内存，而且和很多虚拟化软件冲突；WSL 2方案靠的是轻量级虚拟机，启动快、内存占用可控，和Windows Terminal、VSCode的配合也更顺手一些，所以现在官方默认推荐的就是WSL 2后端。

硬件和系统方面，你只需要满足这几个条件：

• Windows 10 2004（Build 19041）及以上，或者Windows 11
• 系统是64位，且CPU支持虚拟化并在BIOS中已开启
• 内存建议至少8G，实际跑Docker容器8G有点紧，16G会更从容一些
• 安装时确保磁盘有足够剩余空间，Docker Desktop本身占几个G，镜像和数据卷是大头

如果你用的是Windows 10 LTSC或者Windows Server，也能装，但步骤略有不同。LTSC默认不带WSL所需的内核组件，后面执行wsl --update时可能需要手动处理，这个我们在排查章节单独讲。

1.2 WSL 2相比WSL 1和Hyper-V方案到底强在哪

我先用自己的话把这三个方案的区别讲明白，选型就清晰了。

• WSL 1：通过系统调用转换层兼容Linux程序，不需要虚拟化，但网络和I/O性能和真实的Linux环境差得远。跑个MySQL、Redis还行，跑Docker这种依赖完整内核特性的工具就吃力了。
• WSL 2：在轻量级虚拟机里跑一个完整的Linux内核，系统调用完全兼容，Docker容器本质上就是一个进程，直接依托内核能力运行，性能和裸机Linux非常接近。
• Hyper-V方案：本地所有容器都跑在Hyper-V虚拟机里，多一层虚拟化，启动慢，内存开销大，而且Hyper-V一旦开启，VirtualBox、VMware这些工具全部会失灵。

所以我个人建议，只要系统和CPU支持，无脑选WSL 2。

1.3 为什么我不建议用老的Docker Toolbox

早年间Windows上装Docker只能靠Docker Toolbox，它集成的是VirtualBox虚拟机，安装后从虚拟机里转发端口到Windows。这一套在当年确实是个办法，但现在官方已经停止维护了，和Docker Desktop相比没有任何优势：不支持Docker Compose v2、容器内网络问题多、文件挂载性能差、升级麻烦。这篇教程里我没有再提Toolbox，纯粹是基于2025年这个时间点，它已经完全没有折腾的必要了。

2. 动手前先把虚拟化和WSL服务弄明白

2.1 确认CPU虚拟化是否已开启

很多人卡在Docker Desktop启动报错，第一句就是“virtualization support not detected”。这句话翻译过来就是：你的CPU虚拟化没打开。怎么看呢，最简单的办法是打开任务管理器，切到“性能”标签页，点“CPU”，右下角会显示“虚拟化：已启用/已禁用”。

如果显示“已禁用”，需要重启进BIOS开启。Intel的CPU找Intel Virtualization Technology（VT-x），AMD的CPU找SVM Mode，不同主板菜单名不一样，但基本都是这两个关键词。开启后保存重启，再次打开任务管理器确认已启用。

这里有个坑：部分品牌机（尤其是某些轻薄本）BIOS里把虚拟化选项藏得很深，或者默认锁死。这时候可以去Windows功能里勾选“Windows 虚拟机监控程序平台”，重启完再查一次，部分场景下能绕过去，但不是每台机器都适用，后面排查表里我再细化。

2.2 用一条命令安装WSL

确认虚拟化已经开启之后，打开PowerShell，右键选择“以管理员身份运行”，执行：

powershell复制wsl --install

如果系统版本比较新，这条命令会一次性完成三件事：启用WSL功能、安装最新版Linux内核、默认安装一个Ubuntu发行版。中间会自动要求重启电脑，重启后继续。

重启完，Ubuntu会弹出一个终端窗口让你设置Linux用户名和密码。注意WSL里这个用户名和Windows用户名没有关系，建议起一个简单好记的，比如dev，不一定要管理员权限。密码也要记牢，装软件、启动Docker、改配置文件都要用到。

如果没有自动弹出Ubuntu终端，也没关系，打开开始菜单找到Ubuntu图标手动初始化一次。还有一种情况，用户已经装过旧版WSL，需要先把旧版本升级到WSL 2，命令是：

powershell复制wsl --set-default-version 2

这句话的意思是把默认架构切换成WSL 2，之后新装的发行版都以WSL 2模式运行。

2.3 WSL安装特别慢的解决办法

有相当多人遇到wsl --install卡住，或者下载进度半天不动。这里要先区分是卡在哪个环节：如果是Windows功能启用阶段，一般几十秒就完事；如果是下载Ubuntu安装包阶段，那大概率是网络问题，因为发行版安装包是从微软CDN拉取的。

我这边实际测试过的几个办法，按优先级排列：

1. 查看当前发行版状态：

powershell复制wsl -l -v

如果列表里有Ubuntu但状态是“正在安装”，可以再等等。超过半小时不动就继续下一步。

2. 手动下载Ubuntu的appx包。在微软官方WSL发行版页面可以下载Ubuntu的安装包，下载下来后双击安装，或者用Add-AppxPackage命令安装：

powershell复制Add-AppxPackage .\Ubuntu_2xxx.x.x_x64.appx

3. 安装完成后，把默认版本设置为2：

powershell复制wsl --set-default-version 2

4. 检查WSL内核版本：

powershell复制wsl --update

这个命令会单独更新内核组件，某些场景下是因为内核没装到最新版本导致wsl安装卡住。

还有一个冷门但常见的坑：如果你的电脑上装了某些老版本的杀毒软件或安全管家，可能导致wsl的虚拟化平台功能组件改不完整，安装过程看起来像卡住一样。这种情况下先临时退出安全软件，再重跑一次wsl --install，多半能过。

2.4 确认WSL后环境是否正常

安装完成后，先不要急着装Docker，先确认WSL 2核心组件就位。在PowerShell里执行：

powershell复制wsl -l -v

输出的第一列是发行版名称，第二列是状态，第三列是版本。如果前列是Ubuntu，版本是2，那基本就绪了。

接着进入Ubuntu环境，确认Linux用户和包管理工具可用：

bash复制whoami
lsb_release -a
sudo apt update

这里顺便说一下，WSL 2的Ubuntu默认源在国外，apt update速度可能很慢，可以考虑换成国内源。但换源不是必须项，因为后面我们主要用Docker拉镜像，Docker的镜像源是单独配置的，等会儿讲Docker Desktop时再说。

3. Docker Desktop安装与Docker环境配置

3.1 安装Docker Desktop的关键选项

访问Docker官网下载Docker Desktop for Windows，下载的是exe安装包。双击运行之后，安装向导里有一个关键勾选项：Use WSL 2 instead of Hyper-V，这个选项一定要勾上。

安装完成后，Docker Desktop会自动启动，但第一次启动可能比较慢，因为后台要初始化WSL 2环境，并配置一个名为docker-desktop的专用发行版。这个过程可以在通知栏的Docker图标右键菜单里看到状态。

启动完成后，打开终端验证：

bash复制docker version

如果能看到Client和Server两段信息，Server段里有Engine版本号，说明Docker引擎已经在WSL 2里跑起来了。我印象里很多朋友从安装到这一步都很顺利，真正让人头疼的是接下来拉镜像时的网络问题。

3.2 确保Docker Desktop正确连接到WSL发行版

Docker Desktop默认会在WSL 2环境里创建一个docker-desktop发行版来运行引擎，也能让你常用的Ubuntu直接访问docker命令。

怎么确认你的Ubuntu能直接执行docker命令？打开Ubuntu终端：

bash复制docker run hello-world

如果报错找不到docker命令，那就需要打开Docker Desktop的Settings，进入Resources，再进入WSL Integration，确保你的Ubuntu发行版名称在列表中并且已经开启。勾选后，在Ubuntu终端里执行：

bash复制docker ps

能正常输出列表就说明集成成功。之后日常使用不用每次打开Windows的PowerShell去敲docker命令，直接在VSCode的WSL终端里操作即可。

这里提一句，以前配置Docker和WSL集成还需要手动在~/.bashrc里写export DOCKER_HOST之类的内容，现在Docker Desktop会自动处理socket路径，不需要再手改环境变量了。

3.3 国内环境下的镜像加速配置

Docker Hub的镜像拉取速度，在网络条件不理想的时候真的让人抓狂。配置镜像加速器是目前最直接有效的办法。这里说的加速器是指容器镜像仓库的服务地址，比如阿里云的容器镜像服务，注册之后在“镜像中心-镜像加速器”里能看到一个专属地址，格式大概是：

code复制https://xxxx.mirror.aliyuncs.com

拿到地址后，打开Docker Desktop的Settings，进入Docker Engine，把配置改成类似这样：

json复制{
  "registry-mirrors": [
    "https://xxxx.mirror.aliyuncs.com"
  ]
}

改完后点Apply & Restart。然后再去拉镜像，速度会立竿见影。

也可以用国内其他公共镜像源，比如中科大、网易的，配置方式和上面完全一样。但有一点容易踩坑：有些公共源只保留热门镜像，冷门镜像可能拉不到，所以我的习惯是配置两个源，拉不到时自动回落到Docker Hub。

还有一个细节，Docker Desktop本身还有一层“代理”设置，如果你公司网络里有HTTP代理，可以在Settings-Resources-Proxies里配。我不在这里展开，因为普通个人用户一般用不上。

3.4 验证Docker环境整体可用

镜像加速配好之后，跑一个完整的验证，确保不会再出现各种奇怪问题。这一步我通常会做三件事：

bash复制docker version
docker-compose version
docker run --rm hello-world

第一个确认客户端和服务端版本，第二个确认Compose可用，第三个确认镜像拉取和容器启动链路正常。三件事全过，Docker环境基本就稳了。

顺便说一句，如果你以后要用docker compose的v2命令，Docker Desktop最新版默认已经装好了，直接执行docker compose v2版本和相关命令即可。

4. 实战验证：用Compose跑一套MySQL和Redis

光把Docker装起来不算完，我习惯立刻拿一个真实场景验证。这里用一个本地开发常用的组合：MySQL 8.0 + Redis 7，都能在Windows下的WSL 2环境跑起来。这个组合也是很多后端项目的日常依赖。

4.1 创建项目目录和Compose文件

先在Windows文件系统里随便建一个目录，比如D:\docker-study，然后在里面创建docker-compose.yml。这里我建议把项目目录放在Windows侧，这样Docker Desktop挂载文件时走的是WSL 2的跨系统文件映射，性能上没太大问题，而且用VSCode打开也方便。

docker-compose.yml内容如下：

yaml复制services:
  mysql:
    image: mysql:8.0
    container_name: my-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: root123456
      MYSQL_DATABASE: testdb
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

  redis:
    image: redis:7
    container_name: my-redis
    restart: always
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes

volumes:
  mysql-data:

这里有几个关键点：

• 3306和6379端口如果被本机已装的服务占了，会启动失败，可以先检查端口占用，Windows下执行netstat -ano查看。
• MYSQL_ROOT_PASSWORD是测试用的，真实开发环境建议改用环境变量注入方式，或使用更强的密码。
• 给MySQL挂了数据卷mysql-data，重启容器数据不丢。Redis开启了AOF持久化，同样挂卷会更稳妥，但为了简洁这里只开了appendonly。
• 显式声明utf8mb4字符集，避免后续建表时出现中文乱码。

4.2 启动容器并测试连通性

在D:\docker-study目录打开终端，执行：

bash复制docker compose up -d

第一次运行会拉取mysql:8.0和redis:7两个镜像，在有加速器的情况下，几分钟之内能完成。完成后查看状态：

bash复制docker compose ps

如果两个服务的状态都是Up，基本就成功了。接下来测试一下MySQL能不能连进去：

bash复制docker exec -it my-mysql mysql -uroot -proot123456

能正常进入mysql命令行，说明容器网络和认证都没问题。再测试Redis：

bash复制docker exec -it my-redis redis-cli ping

收到PONG，说明Redis可以正常响应。此时这套环境就能当本地开发库用了。

Windows怎么连到这些服务？因为端口已经映射到本机，直接用localhost:3306和localhost:6379即可，数据库工具连接串也可以直接写localhost。

这一套组合跑通，你基本上就已经掌握Docker部署的核心能力了，后面再扩展服务，比如加一个nginx，加一个MinIO，改改Compose文件，重新docker compose up -d就行。

4.3 容器数据与日志的基本操作

本地开发时最怕操作失误把容器删了导致数据全没。这里把数据卷相关的几个常用命令写一下，平时多留意，出问题时不慌：

• 查看数据卷列表：docker volume ls
• 查看某个容器的详细信息：docker inspect my-mysql
• 查看容器日志：docker logs my-mysql
• 停止/启动容器：docker stop my-mysql和docker start my-mysql

还有一点：docker compose down的时候，默认不会删除数据卷，但如果执行了docker compose down -v，数据卷会一并删除，以后这条命令慎用，除非你确定要清理干净。

5. 常见问题与排查技巧实录

部署过程中，最浪费时间的往往不是配置本身，而是一些莫名其妙的报错。我把实际遇到的坑和对应的排查思路整理成一张表，你可以按症状“对号入座”。

5.1 最常见的virtualization support报错

这个报错几乎每周都有人在群里问一遍。我实测下来，90%的情况是BIOS里CPU虚拟化没开，剩下10%是Windows功能没完整启用。

排查步骤：先打开任务管理器确认CPU虚拟化是否已启用。如果显示已启用，那打开Windows功能面板，勾选“Windows 虚拟机监控程序平台”和“虚拟机平台”两个选项，重启后再试试。如果任务管理器显示已禁用，只能进BIOS，没有软件层面的绕路办法。

特别注意，部分旧平台（比如某些7代之前的Intel CPU）需要确认BIOS里到底支不支持SLAT（二级地址转换），Docker Desktop官方文档里写明了这部分要求。但日常遇到的老电脑，十有八九就是BIOS没开，别想复杂了。

5.2 WSL安装或更新卡住的临时解决办法

WSL安装卡住的问题前面提过手动下载发行版包的办法，还有一个更简单的办法：先执行wsl --install，等待5分钟，如果进度条一直没进展，直接按Ctrl+C中断，然后再执行一次wsl --update。这个不保证百分百有效，但在我测过的环境下，有一半概率能绕过下载卡死的情况。

如果是Windows功能层面已经启用但Ubuntu下载失败，可以打开“开始菜单”搜索“适用于 Linux 的 Windows 子系统”，在应用设置里点击“高级选项”，把“让应用访问你的个人信息”设置为开或关再切换一次，然后卸载Ubuntu重新安装。

5.3 环境全部正常但docker命令报错“Can‘t connect to Docker daemon”

这个报错要区分场景。如果是在WSL的Ubuntu终端里出现，多半是Docker Desktop没启动，或者WSL Integration没生效。先确认Docker Desktop已经启动完成，再在Ubuntu里执行docker ps，如果还报错，打开Docker Desktop设置把WSL Integration重新勾选一遍。

如果是在Windows的PowerShell里出现，同样先确认Docker Desktop是否在运行。Docker Desktop启动完毕后会自动挂上socket，不需要手动启动dockerd。

5.4 重启电脑后容器没有自动启动

我一开始也以为重启电脑后容器会自动恢复，后来发现不是这样。Docker Desktop可以设置开机启动，但容器并不会全部自动恢复。想让某个容器随Docker引擎启动而恢复，有两种方式：

• 在Compose文件里给服务加上restart: always，像我前面示例里写的那样
• 手动docker update --restart=always 容器名

这个配置对于本地开发来说非常推荐，避免电脑重启后所有容器都要手动逐个启动的尴尬。

6. 日常使用中的三个心得

6.1 我习惯把项目目录建在Windows侧

在WSL 2里直接操作Linux文件系统速度快，但很多编辑器、IDE在Windows侧更顺手。所以我一般把项目代码放在Windows目录比如D:\projects，然后通过VSCode的WSL插件打开。这样文件映射性能有轻微损耗，但日常开发完全感知不到，而且备份、同步都方便。

6.2 不要动不动就docker compose down -v

本地开发用得很好好的数据，一条down -v全没了。这个命令我吃过一次亏，后来在Compose文件里给数据卷起清晰的名字，并且写进README里提示自己别乱执行。数据卷是Docker里最值钱的东西，操作前先三思。

6.3 把Docker Desktop的WSL Integration和VSCode打通

VSCode装好WSL插件后，可以直接在VSCode里打开WSL目录，终端自动进入Ubuntu环境。此时docker命令、docker compose命令都能直接使用，体验和Linux开发机高度一致。我现在的日常就是：打开VSCode，进入WSL窗口，docker compose up -d，开始写代码。

windows上装docker这套流程，说到底就是把WSL 2底座打牢，再把Docker Desktop接到这个底座上。前期的系统检查、WSL安装、镜像加速这几步做扎实了，之后的使用体验非常顺滑。如果你按照这篇流程走下来的过程中卡在某个环节，不妨再翻一遍第三节和第五节的内容，尤其是那个wsl --update和镜像加速，这两个细节往往是最后解决问题的地方。