安装前的系统检查

确保 Windows 10 版本为 2004 或更高（内部版本 19041 或更高），可通过 winver 命令验证。低于此版本需升级系统或使用 Docker Desktop 替代方案。

启用 WSL 2 功能，以管理员身份运行 PowerShell 执行：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

解决 WSL 2 内核更新失败

下载最新 WSL 2 内核更新包（微软官方链接），安装后执行：

wsl --set-default-version 2

若报错"参考的对象类型不支持尝试的操作"，需禁用 Hyper-V 相关冲突：

netsh winsock reset

配置 Docker Desktop 与 WSL 集成

安装 Docker Desktop 时勾选"Enable WSL 2 Backend"。安装完成后进入 Settings > Resources > WSL Integration，启用对应发行版的集成开关。

若遇到"WSL 2 installation is incomplete"警告，检查 BIOS 中虚拟化技术（VT-x/AMD-V）是否启用，并确保未与其他虚拟化软件（如 VirtualBox）冲突。

解决端口冲突问题

WSL 2 使用独立虚拟机网络，localhost 可能无法直接访问容器端口。解决方案：

• 使用 host.docker.internal 代替 localhost
• 获取 WSL 2 IP 地址：

ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'

• 在 Docker 配置中显式暴露 IPv4 端口：

# docker-compose.yml 示例
services:
  app:
    ports:
      - "0.0.0.0:8080:80"

磁盘空间优化

WSL 2 虚拟硬盘默认自动扩展但不会收缩，定期清理可执行：

# 在 WSL 终端内
sudo apt clean
docker system prune -a

手动压缩虚拟磁盘：

wsl --shutdown
diskpart
# 在 DISKPART 中执行：
select vdisk file="C:\Users\<user>\AppData\Local\Packages\<distro>\LocalState\ext4.vhdx"
compact vdisk

文件系统性能问题

避免在 Windows 文件系统（如 /mnt/c）中操作 Docker 卷，应在 WSL 2 原生文件系统（如 /home）中创建项目目录。跨系统文件操作会导致性能下降和 inotify 事件失效。

对于需要共享的目录，使用 Docker 命名卷而非直接挂载：

docker volume create project_data
docker run -v project_data:/data your_image

解决 DNS 解析故障

若容器内出现 DNS 解析失败，在 WSL 2 中创建或修改 /etc/wsl.conf：

[network]
generateResolvConf = false

然后手动指定 DNS 服务器：

echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

在 Docker 配置中修改 DNS 设置：

// %programdata%\docker\config\daemon.json
{
  "dns": ["8.8.8.8", "1.1.1.1"]
}