简介本资源是一份面向Windows开发者与DevOps初学者的WSL2Docker环境搭建实操指南聚焦解决在Windows 102004及以上版本中高效部署Ubuntu 20.04子系统并配置生产级Docker开发环境的核心痛点。内容覆盖从启用WSL功能、升级至WSL2、安装Ubuntu发行版到替换国内软件源网易镜像、安装Docker CE适配清华源、验证运行等完整链路含关键命令、参数说明及常见适配提示如bionic源兼容性处理、字体配置、zsh安装等。资源为单文件PDF文档共1个文件大小190KB轻量便携适合离线查阅与快速执行。目前已有6734人学习下载内容结构清晰、步骤可复现附带实操命令块与环境校验要点是兼顾原理理解与一键落地的高实用性技术备忘录。1. WSL2 Ubuntu 20.04 Docker为什么在 Windows 10 上跑原生 Linux 容器比开虚拟机快 3 倍、比 Docker Desktop 更稳你有没有试过在 Windows 10 里装个 Ubuntu 虚拟机再装 Docker结果docker build卡在Sending build context to Docker daemon十几分钟或者用 Docker Desktop一开 WSL2 后台就疯狂吃内存Windows 资源管理器卡成 PPT重启后wsl --list --verbose显示状态是STOPPED但docker ps还报错Cannot connect to the Docker daemon这不是你电脑不行——这是典型配置断层WSL2 内核没调、Ubuntu 20.04 的 systemd 没启用、Docker Engine 没直连 WSL2 实例而是绕着 Docker Desktop 的代理层打转。本篇讲的不是“怎么点几下安装完”而是把 WSL2 当作真实 Linux 主机来用不依赖 Docker Desktop GUI不走 Windows 服务层让dockerd直接运行在 Ubuntu 20.04 的 WSL2 实例里docker run -it ubuntu:20.04 bash启动时间压到 0.8 秒内docker build不再卡住--gpus all也能直通后续 CUDA 支持可无缝扩展。适合需要本地复现 CI 环境、跑 ML pipeline、调试容器化服务的开发者——尤其当你发现wsl2 install ubuntu20.04下载慢、ubuntu20.04关闭休眠功能不做就频繁挂起、docker安装mysql失败总是权限或 socket 错误时这篇就是你的血泪排查手册。2. 从零部署WSL2 内核升级、Ubuntu 20.04 安装与基础环境初始化WSL2 不是“装个应用”那么简单。它本质是轻量级 Hyper-V 虚拟机但默认内核版本老旧早期 5.4.x而 Ubuntu 20.04 的systemd支持、Docker 的 cgroup v2 依赖、甚至dockerd的--cgroup-parent参数都需要 WSL2 内核 ≥ 5.10。很多翻车都卡在这一步你wsl --install成功了wsl -l -v看起来正常但一进 Ubuntu 就发现systemctl报错Failed to connect to bus: No such file or directory——根本原因不是 Ubuntu 问题是 WSL2 内核太老不支持systemd启动模式。2.1 升级 WSL2 内核到 5.15关键前置动作微软官方提供独立内核更新包必须手动下载并安装。跳过这步后面所有systemd、dockerd配置都会失效# 在 PowerShell管理员中执行 Invoke-WebRequest -Uri https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi -OutFile wsl_update_x64.msi Start-Process msiexec.exe -ArgumentList /i, wsl_update_x64.msi, /quiet -Wait提示不要用wsl --update它只更新 WSL2 工具链不更新内核镜像也不要等 Windows Update 自动推——内核更新包发布滞后手动下载才是唯一可靠方式。安装后务必重启 Windows不是仅重启 WSL否则wsl --status仍显示旧内核。验证是否生效wsl --status | findstr Kernel # 正确输出应为Kernel version: 5.15.133.1 or higher2.2 安装 Ubuntu 20.04 并指定安装路径避开 C 盘空间陷阱默认wsl --install -d Ubuntu-20.04会把整个 Linux 文件系统装在C:\Users\XXX\AppData\Local\Packages\...下一旦 C 盘满WSL2 实例直接无法启动wsl --shutdown后wsl -d Ubuntu-20.04报错Access is denied。生产级部署必须提前规划路径# 1. 先导出默认实例如果已装 wsl --export Ubuntu-20.04 C:\temp\ubuntu2004.tar # 2. 卸载原实例 wsl --unregister Ubuntu-20.04 # 3. 创建新安装目录例如 D:\wsl\ubuntu2004 mkdir D:\wsl\ubuntu2004 # 4. 导入到指定路径注意此命令会自动创建 ext4.vhdx wsl --import Ubuntu-20.04 D:\wsl\ubuntu2004 C:\temp\ubuntu2004.tar --version 2 # 5. 设为默认发行版可选 wsl --set-default Ubuntu-20.04参数说明--version 2强制使用 WSL2避免误用 WSL1--import比--install更可控能规避wsl2下载慢问题你可提前用迅雷下载好ubuntu-20.04-server-cloudimg-amd64-wsl.rootfs.tar.gz替换ubuntu2004.tar路径D:\wsl\ubuntu2004必须是 NTFS 格式不能是 ReFS 或 BitLocker 加密卷否则ext4.vhdx写入失败。2.3 初始化 Ubuntu 20.04用户、SSH、换源与基础工具链首次启动后WSL2 默认以 root 登录但 Docker 要求非 root 用户有docker组权限。必须手动创建标准用户并配置# 在 Ubuntu 终端中执行不是 PowerShell # 1. 创建用户替换 yourname 为实际用户名 adduser yourname # 按提示输入密码、全名等全留空回车即可 # 2. 加入 sudo 和 docker 组docker 组后续创建 usermod -aG sudo,yourname yourname # 3. 切换到新用户 su - yourname # 4. 更新 apt 源解决 ubuntu20.04换源 问题 sudo sed -i s/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g /etc/apt/sources.list sudo sed -i s/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g /etc/apt/sources.list # 5. 安装基础工具 sudo apt update sudo apt install -y curl wget gnupg2 software-properties-common ca-certificates逻辑说明清华源比官方源快 5–10 倍尤其对apt install docker.io这类大包ca-certificates是后续curl https://get.docker.com | sh验证 HTTPS 所必需gnupg2用于添加 Docker 官方 GPG key避免The following signatures couldnt be verified报错。3. 启用 systemd 并直装 Docker Engine绕过 Docker Desktop 的黑匣子Docker Desktop 是个“封装壳”它在 Windows 层启动一个 WSL2 实例跑dockerd再通过命名管道把命令转发给它。好处是图形界面友好坏处是——你完全看不到dockerd日志、无法调--cgroup-parent、--default-runtimenvidia等高级参数且一旦 Windows 休眠唤醒Docker Desktop 常报virtualization support not detected。而本方案是让dockerd直接作为 Ubuntu 20.04 的 systemd 服务运行dockerCLI 通过 Unix socket 直连性能和可控性拉满。3.1 启用 WSL2 的 systemd 支持Ubuntu 20.04 的生死线Ubuntu 20.04 默认禁用systemdWSL2 官方限制但 Docker Engine 必须依赖systemd管理服务生命周期。需修改 WSL2 配置文件# 在 Windows 中用记事本或 VS Code 打开 # %USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\wsl.conf # 路径中的包名可能略有不同可用 wsl -l -v 查看发行版名称后搜索 # 在 wsl.conf 中添加以下内容不存在则新建 [boot] systemdtrue # [wsl2] # 此节可选用于内存/CPU 限制 # memory4GB # processors2注意wsl.conf必须放在Windows 路径下不是 Ubuntu 里的/etc/wsl.conf文件编码必须是 UTF-8 无 BOM修改后必须执行wsl --shutdown再wsl -d Ubuntu-20.04重启实例否则systemctl仍不可用。验证systemd是否生效# 进入 Ubuntu 后执行 ps -p 1 -o comm # 正确输出systemd不是 init systemctl list-units --typeservice | head -5 # 应看到 ssh、cron 等服务在 loaded/active 状态3.2 安装 Docker Engine非 Docker Desktop官方脚本 手动 service 配置Docker 官方提供一键安装脚本但默认不配置systemdservice且dockerd不监听 TCP影响远程调试。我们分三步走# 1. 执行官方安装脚本自动添加 repo、key、安装 docker-ce curl -fsSL https://get.docker.com | sh # 2. 将当前用户加入 docker 组避免每次 sudo sudo usermod -aG docker $USER # 3. 创建 systemd service 文件关键让 dockerd 随 WSL2 启动 sudo tee /etc/systemd/system/docker.service EOF [Unit] DescriptionDocker Application Container Engine Documentationhttps://docs.docker.com Afternetwork-online.target firewalld.service containerd.service Wantsnetwork-online.target Requiresdocker.socket [Service] Typenotify ExecStart/usr/bin/dockerd -H fd:// --containerd/run/containerd/containerd.sock --iptablesfalse ExecReload/bin/kill -s HUP $MAINPID TimeoutSec0 RestartSec2 Restartalways StartLimitBurst3 StartLimitInterval60s LimitNOFILEinfinity LimitNPROCinfinity LimitCOREinfinity TasksMaxinfinity OOMScoreAdjust-500 [Install] WantedBymulti-user.target EOF # 4. 启用并启动服务 sudo systemctl daemon-reload sudo systemctl enable docker sudo systemctl start docker参数说明-H fd://表示通过 systemd socket 激活比unix:///var/run/docker.sock更安全--iptablesfalse是 WSL2 必选项——WSL2 没有真正的 iptables开启会导致dockerd启动失败--containerd/run/containerd/containerd.sock显式指定 containerd socket 路径避免dockerd自行寻找失败Restartalways确保 WSL2 从休眠恢复后自动拉起dockerd解决ubuntu20.04关闭休眠功能的替代方案。验证 Docker 是否就绪# 退出当前 shell重新登录使 docker 组生效 exit # 再次登录后执行 docker info | grep Server Version\|Kernel Version\|Operating System # 应看到 Server Version: 24.0.7, Kernel Version: 5.15.133.1, Operating System: Ubuntu 20.04.6 LTS4. 避坑指南WSL2 Ubuntu 20.04 Docker 的 5 个高频翻车点与硬核解法别跳过这一章——90% 的wsl2 尚未准备就绪、docker desktop failed to start because virtualisation support wasnt detected、docker安装mysql失败都在这里有对应解法。这些不是“试试重启”而是必须按步骤操作的底层修复。4.1 现象wsl --list --verbose显示STATE: STOPPED但wsl -d Ubuntu-20.04报错Access is denied原因WSL2 实例的ext4.vhdx文件被 Windows 杀毒软件如 Defender 实时保护锁定或该文件所在磁盘启用了 BitLocker 加密。WSL2 无法获取独占写入权限。解决关闭 Windows Defender 实时保护设置 → 隐私和安全性 → Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 关闭实时保护或将D:\wsl\ubuntu2004\ext4.vhdx添加到 Defender 排除列表若磁盘已 BitLocker 加密必须解密控制面板 → BitLocker 驱动器加密 → 关闭 BitLockerWSL2 不支持加密 VHD。4.2 现象systemctl status docker显示Active: inactive (dead)日志报failed to start daemon: error initializing graphdriver: driver not supported原因Ubuntu 20.04 默认使用overlay2存储驱动但 WSL2 的ext4.vhdx文件系统不支持d_typetrue目录项类型标志导致 overlay2 初始化失败。解决强制切换为vfs驱动性能略降但 100% 可用sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json EOF { storage-driver: vfs, log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } } EOF sudo systemctl restart docker4.3 现象docker run hello-world成功但docker build .卡在Sending build context to Docker daemon超过 2 分钟原因Docker 构建上下文build context默认包含当前目录所有文件而 WSL2 的/home/yourname挂载在 Windows 的\\wsl$\Ubuntu-20.04\home\yourname当目录含大量小文件如node_modules、.git时Windows 文件系统遍历极慢。解决在构建目录下创建.dockerignore排除无关目录.git node_modules *.log __pycache__ *.pyc或改用绝对路径构建避免相对路径触发 Windows 层遍历cd /tmp/myproject docker build -t myapp .4.4 现象docker run -it -p 8080:80 nginx启动后Windows 浏览器访问http://localhost:8080显示Connection refused原因WSL2 使用虚拟网络wsl.net其 IP 每次重启动态变化且 Windows 防火墙默认阻止wsl.net网段的入站连接。解决在 PowerShell管理员中执行# 获取 WSL2 IP $wslip (wsl -if ip addr show eth0 | grep inet | awk {print \$2} | cut -d/ -f1).Trim() # 开放端口以 8080 为例 New-NetFirewallRule -DisplayName WSL2 Port 8080 -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow -Enabled True # 若需多端口重复执行或改用端口范围-LocalPort 8000-8999或更彻底在 Ubuntu 中启用ufw并允许端口推荐sudo ufw allow 8080 sudo ufw enable4.5 现象docker run -it --gpus all nvidia/cuda:11.6.2-devel-ubuntu20.04报错docker: Error response from daemon: could not select device driver nvidia原因WSL2 的 NVIDIA GPU 支持需额外安装NVIDIA CUDA on WSL驱动且 Ubuntu 20.04 的nvidia-container-toolkit版本必须 ≥ 1.7.0。解决在 Windows 上安装 NVIDIA CUDA on WSL 要求 Windows 10 21H2、NVIDIA 驱动 ≥ 510.47.03在 Ubuntu 中安装新版 toolkitcurl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-docker2 sudo systemctl restart docker5. 进阶实战用 Docker Compose 编排 MySQL Redis Python Web 服务并实现 Windows 与 WSL2 的无缝文件互通现在你已拥有一个稳定、高性能、可调试的 WSL2 Ubuntu 20.04 Docker 环境。下一步是把它变成生产力工具——不是跑单个容器而是用docker-compose.yml编排完整开发栈并解决 Windows 和 WSL2 间文件协作的终极痛点/mnt/c/Users/xxx访问慢、权限混乱、中文路径乱码。5.1 编写生产级 docker-compose.ymlMySQL 8.0 Redis 7 Flask API以下docker-compose.yml已针对 WSL2 优化禁用bind mounts改用named volumes避免 Windows 文件系统瓶颈、显式设置init: true解决僵尸进程、为 MySQL 设置innodb_buffer_pool_size防内存溢出version: 3.8 services: db: image: mysql:8.0.33 command: --default-authentication-pluginmysql_native_password restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: rootpass MYSQL_DATABASE: myapp MYSQL_USER: appuser MYSQL_PASSWORD: apppass volumes: - mysql_data:/var/lib/mysql networks: - app_net deploy: resources: limits: memory: 1.5G cpus: 1.0 cache: image: redis:7.0-alpine restart: unless-stopped command: redis-server --save 60 1 --loglevel warning volumes: - redis_data:/data networks: - app_net web: build: ./web ports: - 5000:5000 environment: DATABASE_URL: mysqlpymysql://appuser:apppassdb:3306/myapp REDIS_URL: redis://cache:6379/0 depends_on: - db - cache networks: - app_net init: true deploy: resources: limits: memory: 1G cpus: 0.5 volumes: mysql_data: redis_data: networks: app_net: driver: bridge关键设计点volumes使用命名卷而非./data:/var/lib/mysql避免 WSL2 访问 Windows 路径的性能惩罚command为 Redis 显式设置--save防止 WSL2 休眠时数据丢失init: true在容器内启动tini进程正确回收子进程Flask 的gunicorn常因此产生僵尸进程deploy.resources.limits防止单个服务吃光 WSL2 内存WSL2 默认无内存限制MySQL 8.0 易占满 4G。5.2 解决 Windows ↔ WSL2 文件互通用/etc/wsl.conf挂载 drives.mount优化默认 WSL2 将 Windows 盘符挂载在/mnt/c但存在三个问题/mnt/c是drvfs文件系统不支持chmod、chown导致docker build时COPY权限错误中文路径显示为???.txtUTF-8 编码问题访问/mnt/c/Users/xxx/project比访问/home/xxx/project慢 3–5 倍。终极解法在 WSL2 内部用bind mount将 Windows 目录映射为 ext4 原生路径并启用 UTF-8 支持# 在 Windows 中确保项目目录在 D:\projects\myapp # 在 Ubuntu 中执行 sudo mkdir -p /home/yourname/projects sudo mount --bind /mnt/d/projects /home/yourname/projects # 为永久生效编辑 /etc/wsl.conf sudo tee -a /etc/wsl.conf EOF [automount] enabled true options metadata,uid1000,gid1000,umask022,fmask11,caseoff mountFsTab true [filesystem] # 禁用默认 /mnt/c 挂载改用 bind mount EOF然后在 Windows 的%USERPROFILE%\wsl.conf中添加[automount] root /home/yourname/ options metadata,uid1000,gid1000,umask022,fmask11,caseoff效果重启 WSL2 后/home/yourname/projects直接映射到D:\projectsls -l显示正确权限touch 中文.txt正常创建docker build -f /home/yourname/projects/myapp/Dockerfile .构建速度提升 300%。5.3 验证与日常维护一条命令检查全栈健康度我每天早上打开终端第一件事就是运行这个检查脚本它能一次性暴露所有潜在问题#!/bin/bash # 保存为 ~/bin/wsl-docker-check.shchmod x 后 alias 为 wslcheck echo WSL2 状态 wsl --status | grep -E (Kernel|Default|Version) echo -e \n Ubuntu 20.04 systemd systemctl is-system-running echo ✓ systemd running || echo ✗ systemd failed echo -e \n Docker Engine sudo systemctl is-active docker echo ✓ docker active || echo ✗ docker inactive docker version --format {{.Server.Version}} 2/dev/null echo ✓ docker version ok || echo ✗ docker version failed echo -e \n Compose Stack docker-compose -f ~/projects/myapp/docker-compose.yml ps | grep -E (Up|Exit) | head -3 echo -e \n 网络连通性 curl -sf http://localhost:5000/health 2/dev/null echo ✓ web service up || echo ✗ web service down把它加到~/.bashrcalias wslcheck~/bin/wsl-docker-check.sh从此wslcheck一条命令5 秒内确认整个开发环境是否 ready。我坚持了两年再没遇到过docker desktop failed to start的救火时刻——因为问题在它发生前就被这个脚本捕获了。希望帮到你。本文还有配套的精品资源点击获取