Windows 家庭版 WSL2 安装命令行版 Docker 完整教程（无 Docker Desktop

适用场景：Windows 10/11 家庭版，不想装 Docker Desktop，只想在命令行里用 Docker。
本文记录了从环境检查、安装、到解决国内网络拉取镜像的完整过程。

一、先搞清楚：命令行 Docker 一定要 WSL 吗？

只要 docker 客户端、连远程仓库：不需要 WSL，CLI 本身是纯客户端。
要在本机跑 Linux 容器：必须有 Linux 内核，要么 WSL2，要么 Hyper-V 起的 Linux 虚拟机。
Windows 家庭版没有完整 Microsoft-Hyper-V 角色，但有 Virtual Machine Platform + WSL2，足够。
结论：家庭版走 WSL2 是标准且最省心的路。

二、确认虚拟化环境已开启

以管理员 PowerShell 执行：

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform | Select FeatureName, State
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux | Select FeatureName, State

两项都是 Enabled → 直接进第三步。
Microsoft-Hyper-V 查询为空是正常的（家庭版没有该角色），不用管。
systeminfo 里出现「已检测到虚拟机监控程序」说明底层 hypervisor 已开，WSL2 可用。

若某项 Disabled，先开：

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
# 执行后重启

三、安装 WSL 与 Ubuntu 24.04

wsl --install -d Ubuntu-24.04

装完会让你设一个 Linux 用户名/密码（与 Windows 账户无关，随意设）。
启动：wsl -d Ubuntu-24.04，或直接开开始菜单里的 Ubuntu。
若提示 Wsl/Service/WSL_E_DISTRO_NOT_FOUND，说明还没装发行版，执行上面的安装命令即可。

四、在 WSL 内安装 Docker Engine（官方仓库，版本新）

进入 Ubuntu 终端后：

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

想偷懒也可 sudo apt install -y docker.io（版本偏旧但能用）。

五、启动 Docker 并配置免 sudo

sudo service docker start
sudo usermod -aG docker $USER

退出重进 WSL 让 docker 组生效（关终端重开，或 exit 后 wsl -d Ubuntu-24.04）。

六、验证

docker run hello-world

看到 Hello from Docker! 即成功。

⚠️ 国内网络常见报错（下一步解决）：
dial tcp 199.59.150.39:443: i/o timeout（Docker Hub 被墙，连不通）
no such host / Could not resolve host（公共镜像域名解析不了）

七、国内网络必备：镜像加速器 + 修复 DNS

7.1 症状

registry-1.docker.io 能解析但连接超时（egress 被封）。
hub-mirror.c.163.com、docker.mirrors.ustc.edu.cn、mirror.ccs.tencentyun.com 等公共镜像域名解析失败（已停服/被封）。

诊断方法：

for h in registry-1.docker.io docker.mirrors.ustc.edu.cn mirror.ccs.tencentyun.com www.baidu.com; do
  echo -n "$h => "; curl -sI --max-time 6 https://$h >/dev/null 2>&1 && echo OK || echo FAIL
done

www.baidu.com => OK 而 docker 站点全 FAIL → 普通网站能上，但镜像站全封。

7.2 配置可用的第三方加速器

实测可用（请以当时为准，失效就换）：

https://docker.xuanyuan.me
https://docker.1ms.run
https://docker.m.daocloud.io

写入 daemon.json：

sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ]
}
EOF
sudo service docker restart
docker run hello-world

7.3 修复 WSL 的 DNS 回退坑（关键）

WSL 默认 DNS 是自动生成的（如 10.255.255.254 或主机代理设的 ::1）。一旦 WSL 重启，resolv.conf 被重写，可能变成 ::1（本机回环），而 WSL 内没有 DNS 监听 → 解析直接 connection refused，镜像又拉不动。

先写静态 DNS（用公共 DNS，避免依赖主机回环 DNS）：

echo -e "nameserver 223.5.5.5\nnameserver 119.29.29.29" | sudo tee /etc/resolv.conf

再固化，防止重启被覆盖：

sudo tee /etc/wsl.conf > /dev/null <<'EOF'
[network]
generateResolvConf = false

[boot]
command="service docker start"
EOF

然后在 Windows PowerShell 执行（让 WSL 以新配置重启）：

wsl --shutdown

重进 WSL 后确认：

cat /etc/resolv.conf      # 应显示 223.5.5.5，而非 ::1 / 127.0.0.1
docker run hello-world    # 应正常

顺序要点：先写静态 DNS，再设 generateResolvConf=false，最后 wsl --shutdown。这样静态 DNS 会被永久保留。

八、开机自启 Docker

上一步 /etc/wsl.conf 的 [boot] command="service docker start" 已经搞定：WSL 一启动就自动拉起 Docker，无需每次手动 service docker start。

九、在 Windows 侧直接使用 `docker` 命令

不下载 docker.exe、不开端口，让 Windows 的 docker 直接转发到 WSL 执行（走 WSL 的 unix socket，安全）。

PowerShell 版

echo $PROFILE
if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -Type File -Force }
Add-Content -Path $PROFILE -Value 'function docker { wsl -d Ubuntu-24.04 -e docker @args }'
Add-Content -Path $PROFILE -Value 'function docker-compose { wsl -d Ubuntu-24.04 -e docker compose @args }'
. $PROFILE

新开 PowerShell 即可用 docker ps、docker run hello-world。

若用 PowerShell 7+（pwsh），profile 路径不同（C:\Users\leven\Documents\PowerShell\...），需同样加两行函数。

CMD 版（可选）

建 C:\tools\docker.bat（放入 PATH）：

@echo off
wsl -d Ubuntu-24.04 -e docker %*

十、docker-compose 常用模板

已装 docker-compose-plugin，用 docker compose（带空格）子命令。镜像自动走加速器。

# docker-compose.yml
services:
  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - app

  app:
    image: nginxdemos/hello:latest   # 换成您的业务镜像
    expose:
      - "80"

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

docker compose up -d      # 后台启动
docker compose ps         # 看状态
docker compose logs -f    # 看日志
docker compose down       # 停止（保留卷）

浏览器开 http://localhost:8080 验证。

十一、排错速查表

现象	原因	处理
`WSL_E_DISTRO_NOT_FOUND`	没装发行版	`wsl --install -d Ubuntu-24.04`
`dial tcp ...:443: i/o timeout`	Docker Hub 被墙	配 7.2 加速器
`no such host` / `Could not resolve host`	公共镜像域名失效	换成 7.2 里的可用加速器
`lookup ... on [::1]:53: connection refused`	WSL DNS 回退成主机回环	7.3 写静态 DNS + `generateResolvConf=false`
`permission denied` 访问 docker.sock	不在 docker 组	`sudo usermod -aG docker $USER` 后重进 WSL
WSL 重启后 docker 没起	未设自启	`/etc/wsl.conf` 加 `[boot] command="service docker start"`

十二、最终状态总览

✅ Windows 家庭版 + WSL2 + Ubuntu 24.04
✅ Docker Engine（无 Desktop）
✅ 国内加速器 docker.xuanyuan.me 拉取镜像
✅ 静态 DNS 固化，不再回退 ::1
✅ WSL 启动自动起 Docker
✅ Windows 命令行 docker 经 wsl -e docker 直连
✅ docker compose 可用