wsl --list -v 显示不出新装发行版，说明WSL功能未真正激活或发行版安装卡在中间态，常见于Windows功能未启用、hypervisor未配置、内核未更新、发行版未首次运行，或Docker Desktop版本存在docker-desktop-data缺失等已知缺陷。
wsl --list -v 显示不出新装的发行版
说明：Docker Desktop 安装后，wsl --list -v 里看不到 docker-desktop 或 docker-desktop-data，甚至你手动装了 Ubuntu 也压根不出现——这通常不是“没装上”，而是 WSL 功能本身没真正激活，或者发行版安装流程卡在中间态。
常见错误现象包括：wsl --list -v 只输出帮助文本、返回空、或只显示 NAME 表头；wsl -l 报错 0x80370102；Microsoft Store 里点开 Ubuntu 后按钮灰掉、一直转圈。
- 先确认 Windows 功能已启用：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart和dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart都执行过，且已重启 - 检查
bcdedit /enum输出中是否有hypervisorlaunchtype Auto，没有就补一句bcdedit /set hypervisorlaunchtype Auto（必须管理员 PowerShell） - 如果用
wsl --install自动安装失败，别反复重试，直接去 微软官方手动安装页 下载wsl_update_x64.msi装内核，再用wsl --set-default-version 2 - 装完 Ubuntu 后一定要首次启动并完成用户设置，否则 WSL 不会把它注册进列表——光下载不运行，
wsl -l就永远看不见它
Docker Desktop 的 docker-desktop-data 分发版缺失
说明：Docker Desktop 4.31.1 等旧版本存在已知缺陷，安装后只创建 docker-desktop，但 docker-desktop-data 根本不生成，导致所有镜像、容器、卷数据实际写入 C 盘临时目录，重启或重装就清空。这不是你操作失误，是那个版本的 bug。
关键判断点：wsl -l -v 里只有 docker-desktop 一行，没有 docker-desktop-data；\wsl$docker-desktop-dataisocache 路径访问报错 The network name cannot be found；docker images 始终为空。
- 不要用 4.31.1 —— 这个版本被多个实测报告标记为“坑中之坑”，官网已下架，但某些镜像站还在提供
- 换用 4.55.0 或更高版本（2026 年最新稳定版），安装时确保勾选 “Install required Windows components for WSL2” 选项
- 若已安装旧版，先彻底卸载：
wsl --unregister docker-desktop、wsl --unregister docker-desktop-data（即使提示不存在也执行），再删干净%LOCALAPPDATA%Docker和%APPDATA%Docker - 重装后打开 Docker Desktop，等它自动拉起两个分发版，再运行
wsl -l -v确认两者都为Running状态
WSL 集成开关里找不到已装的 Ubuntu 发行版
说明：Docker Desktop 设置 → Resources → WSL Integration 页面显示 You don't have any WSL 2 distros installed，但你明明已在 Microsoft Store 装好 Ubuntu 并能正常进入终端——这是 WSL 注册状态和 Docker Desktop 扫描逻辑不同步造成的。
根本原因在于：Docker Desktop 在初始化时会调用 wsl.exe --list --quiet 获取发行版名，而某些发行版（尤其是通过 Store 安装但未首次运行的）注册信息不完整，或名称含空格/特殊字符，导致匹配失败。
- 确保发行版已启动过至少一次：
wsl -d Ubuntu-22.04（替换成你实际的发行版名），输入密码，退出；再试wsl -l -v - 检查发行版名称是否带空格或大小写异常：
wsl -l输出的 NAME 列值就是 Docker Desktop 匹配用的字符串，比如Ubuntu-22.04≠ubuntu-22.04 - 重启 Docker Desktop，而不是只刷新设置页——它只在启动时扫描一次 WSL 列表
- 如果仍不识别，临时改名：
wsl --export Ubuntu-22.04 ubuntu2204.tar && wsl --unregister Ubuntu-22.04 && wsl --import Ubuntu2204 .ubuntu2204.tar --version 2，再启用集成
docker-desktop 分发版状态卡在 Uninstalling 或 Not Found
说明：wsl -l -v 中 docker-desktop 显示 Uninstalling，或 Docker Desktop 启动时报 WSL_E_DISTRO_NOT_FOUND，意味着它的 WSL 环境损坏但残留配置未清理干净，Docker Desktop 每次启动都试图终止一个不存在的分发版，陷入死循环。
这种状态往往伴随 wsl --terminate docker-desktop 报错、docker version 显示 client OK 但 server unreachable、任务栏鲸鱼图标卡在 starting。
- 强制注销所有残留：
wsl --unregister docker-desktop和wsl --unregister docker-desktop-data，哪怕提示“not found”也继续执行 - 删掉 WSL 虚拟磁盘文件：
%LOCALAPPDATA%PackagesDigitalEntitlementsLocalStateext4.vhdx（如有）、%LOCALAPPDATA%Dockerwsldataext4.vhdx（如有） - 关闭 Docker Desktop，执行
wsl --shutdown，再手动删掉%USERPROFILE%AppDataLocalDockerwsl整个目录 - 重启系统，再启动 Docker Desktop——它会重新创建两个分发版，这个过程可能需要 2–5 分钟，期间不要中断或重复点击启动
最常被忽略的一点：Docker Desktop 对 WSL 的依赖不是“装了就行”，而是要求整个链路——从 BIOS 虚拟化开关、Windows 功能启用、hypervisor 配置、WSL 内核更新、到发行版首次运行——全部闭环成功。任何一个环节断开，都会表现为“发行版不在列表里”，但根因可能差着三层系统调用。
