一句话总结：要在 Windows 上用 Docker 调用 NVIDIA GPU，必须在 WSL2 的 Linux 终端中操作，且需使用 runtime 镜像。
💡 为什么需要这套组合？
很多开发者习惯在 Windows 上工作，但深度学习、AI 推理等任务又严重依赖 Linux + CUDA 生态。过去只能装双系统或忍受虚拟机性能损失。
如今，WSL2 + Docker Desktop + NVIDIA 驱动三位一体，让你在 Windows 中获得近乎原生的 GPU 加速体验。
✅ 前提条件
🔧 详细安装步骤（从零开始）
第一步：启用 WSL 和虚拟机平台
以 管理员身份 打开 PowerShell（右键开始菜单 → Windows PowerShell (管理员)），运行：
# 启用 WSL 和虚拟机平台
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
⚠️ 执行后必须重启电脑。
第二步：安装 WSL2 内核更新
wsl —set-default–version 2
第三步：安装 Linux 发行版（如 Ubuntu）
📌 此时你已拥有一个完整的 Linux 子系统！
第四步：安装 NVIDIA 驱动（仅需在 Windows 安装！）
✅ 验证：重启后，在 Windows 桌面按 Win + R → 输入 cmd → 运行：
nvidia-smi
如果看到 GPU 信息，说明驱动安装成功。
📌 重要：不要在 WSL2 的 Ubuntu 中安装 NVIDIA 驱动！WSL2 会自动继承 Windows 驱动。
第五步：安装 Docker Desktop for Windows
在 Settings 中确认以下选项：
- General → ✅ Use the WSL 2 based engine
- Resources → WSL Integration → ✅ Enable integration with your installed WSL distro（如 Ubuntu-22.04）
💡 启用集成后，Docker 命令会自动在 WSL2 中可用，无需额外配置 PATH。
🔍 详细检查步骤（验证是否成功）
检查 1：确认 WSL2 版本
在 PowerShell 中运行：
wsl –l –v
✅ 正确输出示例：
NAME STATE VERSION
* Ubuntu-22.04 Running 2
如果 VERSION 是 1，请升级：wsl –set-version Ubuntu-22.04 2
检查 2：在 WSL2 中验证 GPU 可见性
✅ 成功输出 GPU 型号、驱动版本、显存等信息 ❌ 失败可能原因：NVIDIA 驱动未更新（需 ≥ 515.48.07）
📌 注意：此命令在 WSL2 中能运行，证明 Windows 驱动已正确暴露给子系统。
检查 3：测试 Docker GPU 支持（关键！）
仍在 Ubuntu 终端中执行：
# 拉取官方 runtime 镜像（含 nvidia-smi）
docker pull nvidia/cuda:12.4.0-runtime-ubuntu22.04
# 运行 GPU 测试
docker run –rm –gpus all nvidia/cuda:12.4.0-runtime-ubuntu22.04 nvidia-smi
✅ 成功输出与 nvidia-smi 相同的 GPU 信息 ✅ 容器退出后自动删除（因 –rm）
⚠️ 必须在 WSL2 终端运行！ 在 Windows CMD/PowerShell 中运行会失败或无法访问 GPU。
检查 4：验证 CUDA 版本兼容性
容器内显示的 “CUDA Version: 12.4” 是驱动支持的最高 CUDA 版本，不是容器实际使用的版本。
要查看容器内真实 CUDA 版本：
docker run –rm –gpus all nvidia/cuda:12.4.0-runtime-ubuntu22.04 cat /usr/local/cuda/version.txt
输出应为：
CUDA Version 12.4.0
🛠️ 常见问题与解决
| nvidia-smi: command not found in container | 改用 runtime 或 devel 镜像，勿用 base |
| could not select device driver "" with capabilities: [[gpu]] | 确认在 WSL2 终端运行；重启 Docker Desktop |
| 拉取镜像时报 failed size validation | 在 WSL2 中执行 docker system prune -af，重启 Docker Desktop |
| WSL2 中 nvidia-smi 报错 | 升级 Windows 端 NVIDIA 驱动至最新版（≥ 550） |
| Docker Desktop 无法连接 WSL2 | 在 PowerShell 执行 wsl –shutdown，再重启 Docker |
🌟 总结
通过以上步骤，你已完成：
- ✅ WSL2 安装与配置
- ✅ NVIDIA 驱动正确安装（仅 Windows 端）
- ✅ Docker Desktop 与 WSL2 集成
- ✅ GPU 在 Docker 容器中可用
现在，你可以无缝运行 PyTorch、TensorFlow、Ollama、Stable Diffusion 等支持 CUDA 的应用，享受本地 GPU 加速！
记住黄金法则：所有涉及 GPU 的 Docker 命令，必须在 WSL2 的 Linux 终端中执行。
日期：2026 年 4 月 13 日 测试环境：Windows 11 23H2 + RTX 4070 + Docker Desktop 4.30 + NVIDIA Driver 550.42 + Ubuntu 22.04 LTS
