先直接说结论这个报错只发生在 WSL 尝试下载发行版列表那一步跟你电脑上已经装好的 WSL 内核没太大关系遇到它不代表你系统坏了也不代表 WSL 不能用了。真正的问题是这个安装流程需要访问 GitHub 上的一个分发列表文件而很多网络环境下这条链路特别不稳定于是就会看到“无法从 raw.githubusercontent.com 提取分发列表、操作超时”这类提示。这篇文章我会把这个报错从现象到根因掰开讲一遍然后给你几条绕过这条网络路径的实用方案。不管你是刚接触 WSL 的小白还是已经在 WSL 里折腾 Docker、CUDA、binwalk 的老手只要被这个超时卡住过下面这些内容都能直接拿去抄作业。1. 报错现场与根因拆解1.1 这个报错长什么样通常你输入这条命令时最容易触发wsl --install -d Ubuntu-22.04或者干脆就是不带参数的wsl --install命令执行后卡一会儿然后输出类似这样的错误无法从 https://raw.githubusercontent.com/microsoft/wsl/master/distributions/distributions.json 提取发行版列表操作超时 未能成功安装发行版。有些版本还会把错误描述写成“无法提取分发列表”或者直接抛一个网络异常。别管文案差异本质都一样WSL 启动安装流程后需要先从一个远程地址拉取一份发行版清单然后再根据清单去下载你指定的那个发行版镜像。这一步卡住了后面的安装自然就进行不下去。还有一类变体不是超时而是返回 403。这种 403 我在不同电脑上碰到过几次原因是那条 raw 地址的访问行为被服务器判定为“不太正常”。不管是超时还是 403绕法是一样的后面会统一说。1.2 为什么 WSL 非要去连接 raw.githubusercontent.com很多人不理解我用的是微软的 WSL 功能为什么安装过程要去访问 GitHub这个得从 WSL 的安装机制说起。wsl --install在一开始会读取一个名叫distributions.json的文件里面记录了当前 WSL 能安装哪些发行版、每个发行版的下载地址、默认参数等信息。这个文件由微软官方维护但历史原因一直放在 GitHub 的microsoft/wsl仓库里具体就是https://raw.githubusercontent.com/microsoft/wsl/master/distributions/distributions.json所以整个安装链路是这样的WSL 下载distributions.json拿到发行版清单根据清单找到目标发行版的下载链接再从对应链接下载安装包并注册到 WSL 中。如果你只是运行wsl --version或者wsl --status根本不会碰这个地址。只有执行安装发行版相关操作时才会引入这个外部依赖。这也是为什么很多人用着用着 WSL 没问题一装新发行版就报网络错误。1.3 为什么偏偏是“操作超时”“操作超时”这四个字很多人第一反应是电脑配置不够其实不对。这一步纯粹是网络层面的问题。raw.githubusercontent.com 这个域名背后的服务器在美国CDN 节点在海外的覆盖情况不如国内访问顺畅加上 DNS 解析偶尔被污染用两三百毫秒甚至更久才能建立连接一旦超过 WSL 内部设置的等待时间就会直接判定超时。我在测试过程中还发现一个规律同一个网络环境下浏览器多刷新几次 raw 地址可能能打开但命令行工具因为走的是系统底层网络栈超时阈值更短失败概率反而更高。换句话说你的网络不是完全不能用只是“不够稳定、不够快”而 WSL 安装过程对这条链路的稳定性要求比较高。明白这一点之后解决方案的思路就很清晰了要么优化网络链路的稳定性和响应速度要么彻底绕开 raw.githubusercontent.com 这条路径。2. 对症下药先别急着重装先排查网络链路2.1 第一轮排查测通不通、看看 DNS在决定用离线方案之前我建议你先花两分钟做一次基础排查。知道自己卡在哪一层后面才会更从容。打开 PowerShell依次敲这几条命令Test-NetConnection raw.githubusercontent.com -Port 443如果返回TcpTestSucceeded : True说明 TCP 层能连通问题大概率出在传输速度或 TLS 握手环节。如果返回False那说明当前网络到这台服务器的链路基本是堵死的靠重试很难解决。接着查 DNS 解析结果Resolve-DnsName raw.githubusercontent.com留意返回的 IP 地址是不是离你特别远。正常情况下这个域名在不同地区会解析到不同 CDN 节点但如果解析出的地址响应很慢或者与你本地网络明显不匹配就说明 DNS 这一层已经不太健康了。2.2 清洁工模式清空 DNS 缓存并更换公共解析如果 DNS 解析速度不稳定可以先清掉本机缓存再把 DNS 临时切到公共解析服务。Windows 下清 DNS 缓存很简单ipconfig /flushdns然后进入网络适配器的 IPv4 属性把首选 DNS 改成223.5.5.5备用 DNS 改成119.29.29.29。这两个分别是阿里和腾讯的公共 DNS国内访问速度通常比运营商默认 DNS 更好。改完之后再跑一次Test-NetConnection看延迟和连通性有没有改善。这一步不会影响任何已有系统配置网络恢复正常后你可以随时改回去。大部分临时性超时问题在换公共 DNS 之后就能缓解。但我要提前打个预防针如果问题出在链路本身的稳定性上只改 DNS 不一定能根治它只是排查流程里成本最低的一步。2.3 换一个网络环境成功率翻倍还有一个老生常谈但确实有效的招换个网络环境。比如从公司内网切到手机热点或者从 Wi-Fi 切到有线宽带。我实测过很多次同一个报错在移动网络下重试装 WSL成功率明显比某些固定宽带更高。原理不复杂不同运营商到海外服务器的路由质量差异很大有些线路存在绕路和拥堵TLS 握手长时间没有响应自然就超时。换一个网络环境相当于换了一条路径很多时候不需要做任何额外配置就直接成功了。如果你不方便换网络还可以试试在 PowerShell 里执行wsl --update --web-download这一步会单独更新 WSL 组件把内核相关文件从微软自家服务器拉下来。虽然它不解决distributions.json的下载问题但能保证 WSL 本体是最新状态避免后面因为版本太旧又冒出一堆新问题。2.4 绕开 raw.githubusercontent.com从微软官方渠道装如果以上网络手段都试过没用那就别死磕 raw 地址了。WSL 安装发行版并不只有wsl --install这一条路。微软提供了好几条发行版分发渠道比如 Microsoft Store 里的 WSL 发行版页面再比如微软官方维护的 rootfs 压缩包。这些资源的服务器都在微软自己的 CDN 上跟 raw.githubusercontent.com 完全是两套基础设施绕过去之后很多网络问题自然就消失了。你可以先试wsl --install --no-distribution这句话的意思是先把 WSL 本体组件装好不安装任何发行版。等这一步成功再用下面的离线方案单独添加一个 Ubuntu。3. 最稳方案离线安装 Ubuntu 到 WSL3.1 方案 A用 Microsoft Store 安装发行版这是最接近“一键安装”的替代方案。打开 Microsoft Store搜索“Ubuntu”你会看到 Ubuntu、Ubuntu 20.04、Ubuntu 22.04 等多个版本。选择其中一个点击安装剩下的都是由 Store 下载并处理。Store 走的是微软自己的分发通道通常比 raw.githubusercontent.com 稳定得多。安装完成后从开始菜单启动 Ubuntu 终端第一次启动会让你创建用户名和密码。创建完成之后你可以在 PowerShell 里输入wsl -l -v应该能看到已经注册的发行版信息。这个方法唯一的缺点是 Store 在某些精简版 Windows 系统里被移除了或者登录 Store 需要一点时间。碰到这种情况直接看方案 B。3.2 方案 B手动下载 .appx 包再安装微软官方除了 Store 之外还提供一个网页端分发页面地址格式是https://aka.ms/wslubuntu2204这类短链。用浏览器打开这个地址可以直接下载到一个.appx或.appxbundle格式的安装包。拿到安装包后在 PowerShell 里执行Add-AppxPackage .\Ubuntu2204.appx如果系统提示需要安装证书或依赖通常是因为缺少 VCLibs 组件。报错时它会明确告诉你缺什么东西你到微软官网下载对应的 VC 运行库装上再重新执行上面的命令就行。安装完成后同样从开始菜单启动一次 Ubuntu完成初始化用户配置。这个方法的好处是不需要 Store 客户端只要浏览器能打开aka.ms短链就能搞定。如果连aka.ms都打不开那还有更底层的办法往下看。3.3 方案 C用 rootfs 镜像导入wsl --import最后这个方法最“硬核”但也最可靠因为 rootfs 压缩包可以从多个渠道获取只要能下载到文件就万事大吉。它的核心是借助wsl --import命令把一个完整的根文件系统镜像导入 WSL。步骤是这样的先准备好一个 Ubuntu rootfs通常是.tar.gz格式。你可以从 Ubuntu 官方云镜像地址下载也可以从微软文档里提供的链接下载注意选择 WSL 专用版本。解压或直接保留压缩包记住它在磁盘上的位置。在 PowerShell 里创建一个目录用来存放 WSL 的虚拟磁盘文件。mkdir D:\WSL\Ubuntu2204执行导入命令wsl --import Ubuntu2204 D:\WSL\Ubuntu2204 D:\downloads\ubuntu2204.tar.gz --version 2参数从左到右分别是发行版名称、安装目录、rootfs 文件路径、WSL 版本这里建议用 2性能和完整度都更好。导入成功后。用wsl -d Ubuntu2204进入系统。这种情况下默认用户是 root如果你更习惯用普通用户可以手动创建一个用户并设置默认用户。这个方案最大的优点是完全不依赖微软的发行版分发服务只要能手动搞到 rootfs 文件剩下的都在本地完成非常适合网络受限环境。3.4 装完以后必做的三件事离线装好 Ubuntu 只是第一步有几个收尾工作我强烈建议你立刻做否则后面还会踩坑。第一件事设置默认发行版和默认用户。在 PowerShell 里执行wsl -s Ubuntu2204 wsl -d Ubuntu2204然后用adduser创建日常使用的账号再编辑/etc/wsl.conf[user] default你的用户名保存后退出 WSL运行wsl --terminate Ubuntu2204再重新进入默认用户就生效了。第二件事立刻更新软件源。新装的 Ubuntu 默认源在海外速度可能很慢。编辑/etc/apt/sources.list把archive.ubuntu.com和security.ubuntu.com替换成国内镜像域名例如阿里云镜像源或清华镜像源。第三件事升级一次系统sudo apt update sudo apt upgrade -y这一步能解决大部分软件包版本过旧的问题后续安装 Docker、CUDA、编译工具链时会更顺畅。4. 高频后续问题与避坑记录4.1 “你的 WSL 版本太旧”与内核更新离线安装完 Ubuntu 后如果你用wsl --version发现版本很老或者系统提示 “your version of windows subsystem for linux (wsl) is too old”不要慌。先执行wsl --update如果这条路也不通就手动下载 WSL 的更新安装包微软官方提供 MSI 文件。下载后双击安装即可。装完重启终端再运行wsl --version应该能看到版本号更新到最新。要特别提醒老版本 WSL 和新版本内核之间有一些行为差异尤其是 GPU 直通、systemd 支持这些功能。如果你后面要用 WSL 跑 CUDA 或者通过 systemd 管理服务一定要先把内核和用户态组件更新到较新版本。4.2 wsl --install 太慢、卡在下载阶段怎么办除了distributions.json超时之外还有人会遇到wsl --install执行后长时间卡住不动网速显示只有几 KB/s。这种情况多半是正在下载发行版镜像而这个镜像地址同样有不稳定的问题。我的建议是不要跟它硬耗。直接 CtrlC 中断换用前面提到的 Store 或离线包方案。微软官方确实有一个aka.ms的下载链接如果你发现下载速度很慢可以换个时间再试或者借用能正常访问的下载工具先拉下来再拷贝到目标机器上安装。另外注意wsl --install默认会先安装 WSL 虚拟化平台组件这一步需要开启 Windows 功能并重启电脑。如果你发现命令卡在“正在启用功能”阶段先去“启用或关闭 Windows 功能”里确认“适用于 Linux 的 Windows 子系统”是否已经勾选没勾选就先打勾重启后再继续。4.3 在 VSCode 里使用 WSL 时常见的连接问题很多人折腾 WSL 的目的是为了在 VSCode 里写代码。VSCode 连接 WSL 靠的是 “WSL” 扩展和codeCLI 工具。正常情况下你在 VSCode 里按CtrlShiftP输入 “WSL”选择 “Connect to WSL” 就能连上。但是如果你的 WSL 发行版是手动通过wsl --import导入的默认用户是 rootVSCode 连接后可能会提示没有安装服务器依赖或者权限不对。解决办法就是前面讲的配置好wsl.conf里的默认用户然后重新启动发行版。还有一类问题是 VSCode 找不到 WSL 路径。这通常是因为你装的是早期版本的 WSL或者系统里残留了旧版本命令行工具。重装最新 WSL 后重启 VSCode一般就正常了。4.4 apt 源太慢换国内镜像源新装 WSL 之后如果sudo apt update时速度很慢八成是软件源默认指向了海外服务器。换国内镜像源是最有效的优化手段。以 Ubuntu 22.04 为例把/etc/apt/sources.list里的域名改成镜像站地址再执行sudo apt update sudo apt upgrade -y实测换完之后速度提升非常明显。如果你用的是 Ubuntu 24.04 或更新版本软件源配置可能移到了/etc/apt/sources.list.d/ubuntu.sources修改原理一样找到带URIs:的那行替换即可。换完源之后还有一个容易被忽略的小坑证书问题。如果apt update报错说无法验证镜像站签名先确认系统时间对不对时间偏差大了会出现证书校验失败。用sudo ntpdate ntp.ubuntu.com同步一下时间再执行更新就正常了。5. 我个人踩坑后的一些体会写到这里回顾一下整个过程我最想说的一句话是遇到 “raw.githubusercontent.com操作超时” 这类报错心态不要崩也不要去反复wsl --install硬试不会有用的。重点是怎么换一条更稳的路径把发行版装进来。在我实际维护 WSL 环境的经验里最省心的组合其实是“Store 安装发行版 wsl --update更新内核 换国内 apt 源”。这套流程几乎不依赖海外链路安装速度快后续维护也省事。另外一个小技巧如果你经常在多台电脑上配置 WSL弄完一台之后把关键的离线包、配置文件比如.wslconfig备份到自己的云盘里下次遇到同样问题时直接拷贝过去能省下很多重复折腾的时间。最后如果这篇文章里的方案帮你解决了问题欢迎转发给同样被 WSL 报错折磨的朋友。折腾环境本来就是一件需要耐心的事把经验沉淀下来就能少走很多弯路。