创建虚拟安卓设备一直是很多 .NET MAUI 开发者绕不过去的坎。本地环境明明没问题项目也能编译偏偏在执行maui-check或者手动创建 Android 模拟器时弹出一个含糊的“网络异常”。我之前在这个坑边蹲了好几天试过删缓存、重装 SDK、改 hosts最后才发现真正的问题出在默认的 Android SDK 仓库源上——只要把下载源切到清华镜像整个过程立刻顺畅了。这篇文章就把我处理“MAUI 创建虚拟安卓设备提示网络异常”的完整思路、具体改法以及踩坑记录都写出来希望对被困在这一步的人有帮助。适合谁看很简单用 .NET MAUI 开发、需要在本机跑 Android 模拟器但被下载源或者网络连通性问题卡住的人。不管你是刚入门的新手还是熟悉电脑操作但第一次碰 Android SDK 的老手按下面的步骤都能处理掉大部分“网络异常”报错。1. 现象MAUI 创建虚拟安卓设备时网络异常到底长什么样很多人看到“网络异常”四个字就以为是公司网络、家用宽带的问题然后开始折腾路由器、DNS结果毫无用处。这里先花点篇幅把我在不同环境里遇到的报错现象逐一列出来方便你对号入座。1.1 最容易踩中的几个报错场景.NET MAUI 创建虚拟安卓设备通常不会只走一条路。不同入口操作最终遇到的网络报错也有细微差别。场景一maui-check 检查环境时失败。这是图省事的人最喜欢用的方式一条命令检查所有开发依赖。前面输出大半屏的绿色对勾到 Android SDK 相关步骤时突然变红提示类似Failed to install Android SDK components. Network error: Connection timed out.时区不对的话它也会一直卡在“Downloading...”等几分钟后直接超时退出。场景二Android SDK Manager 图形界面里点安装组件失败。很多人在 Visual Studio 里打开 Android SDK Manager勾上 Platform-Tools、System-Images点击安装进度条走一丢丢就报错。日志里常见的句子有java.io.IOException: Server returned HTTP response code: 502 for URL: https://dl.google.com/android/repository/repository2-3.xml场景三命令行直接创建 AVD 时失败。使用avdmanager创建虚拟设备它需要先下载系统镜像。镜像文件动辄几百 MB如果仓库源连不上就会提示Error: AVD creation failed. Failed to create sd card. Downloading...实际上真正失败的步骤是系统镜像下载。1.2 为什么 .NET MAUI 环境检查会死在这一步.NET MAUI 本身只是应用框架它并不内置 Android SDK。所有和安卓编译、模拟器运行相关的底层组件都依赖本机的 Android SDK。maui-check这类工具本质上是个“检查和安装引导器”它检测到缺组件时会尝试调用 SDK 管理器去下载。也就是说网络异常不是 MAUI 自己网络出了问题而是它底层的 Android SDK 组件下载流程出了问题。搞清楚这层关系后思路就清晰了只要能让 Android SDK 的下载流程顺利走完MAUI 创建虚拟安卓设备这条路就通了一半。另外有一点值得注意国内很多开发者装 Visual Studio 时会顺手勾选“Android SDK”但这个组件包并不完整。MAUI 模拟器还需要额外的 system-images 和 platform-tools这些组件默认从 Google 的服务器拉取。对部分网络环境来说连上这个服务器并稳定下载完大文件真的不是一件轻松事。2. 根因不是“网络坏了”而是默认下载源离你太远报错信息都叫“网络异常”但真实原因很少是“没网”。你自己打开浏览器逛逛新闻、看看视频网络都正常得很。问题恰恰出在四件事上。2.1 Android SDK 组件到底要从哪下载Android SDK 的各组件包括platform-tools、platforms、system-images、build-tools背后都有一个仓库清单文件。默认配置下SDK 管理器会去访问https://dl.google.com/android/repository/。这个仓库清单会告诉 SDK 管理器现在有哪些版本、各自下载地址是什么。换言之下载动作不是从单个固定地址拉文件而是先取回一个 XML 清单再根据清单里的地址逐一下载。这个机制有一个特点只要清单地址不通后面全部白搭只要清单里的某个下载地址连通性差就会表现为“下载到一半失败”或者“某些组件能装某些组件不能装”。2.2 网络异常背后常见的三个因素实际排查下来导致这个仓库地址连接异常的原因大致有三类。第一类是最常见的“连接超时”。默认源在网络链路较远的情况下TCP 握手本身就很慢访问 XML 清单超过 SDK 管理器的等待阈值直接判定网络异常。这不是说绝对连不上而是“慢到不可用”。第二类是“文件下载中断”。系统镜像文件少则几百 MB多则 1 GB 以上。长连接期间一旦出现波动下载就断而 SDK 管理器对断点续传的支持又不理想重试几次都从 0 开始最终放弃并报错。第三类是“版本索引和本地缓存不一致”。SDK 管理器会在本地缓存仓库清单。如果之前有几次失败留下一个不完整的 XML 缓存后续再检查时它会误以为仓库已经是最新却不尝试重新拉取。这种情况下换镜像源往往同时解决了“连不上”和“缓存错乱”两个问题。2.3 为什么“换镜像”是最直接的解法换镜像的本质是把“从默认源下载”变成“从一个网络连通性更好的仓库下载”。开源镜像站一般会定时同步 Android SDK 仓库内容你请求的文件内容和官方仓库一致但服务器在国内或者距离更近的节点下载速度与稳定性都会有明显改善。这不需要改项目代码不需要调整 MAUI 框架配置也不会影响模拟器运行效果。它属于纯粹的开发环境层面的调整风险极低。如果改完还是不生效你也只需要把改动还原不会对系统造成任何副作用。所以在面对“网络异常”时第一反应不该是怀疑 DNS也不该去动 hosts 文件而是优先检查 SDK 管理器正在使用哪个仓库源。这是一个成本最低、效果最直接的排查方向。3. 实操把 Android SDK 仓库切到清华镜像一步步来说再多原理不如直接给一套能照着做的步骤。下面以我在 Windows 上的操作为例macOS 和 Linux 的差异会在后面单独说明。3.1 准备确认 Android SDK 目录与命令行工具镜像源修改不是写在 MAUI 配置里的而是写在 Android SDK 自身的命令行工具里。所以第一步要找到 SDK 装在哪以及有没有可用的cmdline-tools。在 Visual Studio 安装 MAUI 工作负载时Android SDK 默认会被装到%LOCALAPPDATA%\Android\Sdk也就是当前用户目录下。用命令行查看echo $env:LOCALAPPDATA\Android\Sdk正常会输出类似C:\Users\你的用户名\AppData\Local\Android\Sdk。注意如果你之前单独装过 Android StudioSDK 也可能在C:\Users\你的用户名\AppData\Local\Android\Sdk或者D:\Android\Sdk这种自定义路径。不管在哪后面都围绕这个目录操作。进入目录后需要检查是否存在cmdline-tools文件夹尤其是cmdline-tools\latest\bin下有没有sdkmanager.bat和avdmanager.bat。如果不存在说明当前 SDK 缺少命令行工具很多后续操作无法直接执行。提示我遇到过一种情况——SDK 目录里压根没有cmdline-tools只有platforms和build-tools。这种情况下与其手工补文件夹结构不如直接下载一份命令行工具压缩包解压进去后面会讲具体下载路径。3.2 修改 sdkmanager 的仓库地址sdkmanager 在启动时会读取一个名为repository.xml的仓库清单。默认地址被硬编码在启动脚本里但我们可以在脚本层面通过 Java 系统属性覆盖。Windows 下用文本编辑器打开C:\Users\你的用户名\AppData\Local\Android\Sdk\cmdline-tools\latest\bin\sdkmanager.bat找到类似下面的内容rem Set Andoid SDK Manager repository URL set repo_urlhttps\://dl.google.com/android/repository/repository2-3.xml如果没有看到显式的repo_url可以找到call %java_exe%那一行在其前面追加一行JAVA_OPTS设定set JAVA_OPTS%JAVA_OPTS% -Dandroid.sdk.repository.urlhttps://mirrors.tuna.tsinghua.edu.cn/AndroidSDK/repository/repository2-3.xml注意在批处理脚本里原本的 URL 中冒号被写成了\:这是为了防止冒号被解析成盘符路径。新加的这段如果直接写冒号也可能被批处理误判。稳妥做法是沿用同样的转义格式set JAVA_OPTS%JAVA_OPTS% -Dandroid.sdk.repository.urlhttps\://mirrors.tuna.tsinghua.edu.cn/AndroidSDK/repository/repository2-3.xmlmacOS 和 Linux 下对应文件是cmdline-tools/latest/bin/sdkmanager。用编辑器打开找到CLASSPATH相关部分新增一行JAVA_OPTS$JAVA_OPTS -Dandroid.sdk.repository.urlhttps://mirrors.tuna.tsinghua.edu.cn/AndroidSDK/repository/repository2-3.xml这里不需要转义冒号直接用普通字符串即可。修改完成后在命令行执行sdkmanager --list如果输出了一大串可用组件列表而不是报网络错误说明镜像源已经生效。这一步是整个处理流程的关键验证点。3.3 安装缺失组件platform-tools、platforms、system-images仓库源切换成功后接下来要做的事情就是按需安装组件。MAUI 创建虚拟安卓设备通常至少需要platform-tools一个platforms;android-XX版本一个与模拟器 CPU 架构匹配的system-images;android-XX;google_apis;x86_64我当时的命令如下sdkmanager platform-tools platforms;android-34 system-images;android-34;google_apis;x86_64执行过程中SDK 管理器会先询问是否接受许可协议Accept? (y/N):这里很多人会习惯性一个个输入y比较麻烦。可以直接执行yes | sdkmanager platform-tools platforms;android-34 system-images;android-34;google_apis;x86_64让管道自动把y喂给所有许可询问。提醒安卓版本的编号并不一定和 MAUI 支持的最高版本相同。做项目时优先选择和项目TargetFramework匹配的平台版本。比如项目目标是net8.0-android34.0那就选android-34。盲目装最新版反而可能在 MAUI 构建时出现 API level 不匹配的警告。3.4 用 avdmanager 创建虚拟设备并启动组件装好之后虚拟设备本身需要一个“设备定义”。MAUI 的开发者通常喜欢直接跑默认模板但命令行方式更稳。先看现有的设备定义avdmanager list device找一个像素密度、屏幕尺寸合适的定义比如pixel_5。然后创建 AVDavdmanager create avd -n MauiTest -k system-images;android-34;google_apis;x86_64 -d pixel_5创建时可能会问“Do you wish to create a custom hardware profile? [no]”直接回车选择默认即可。启动模拟器emulator -avd MauiTest如果emulator命令不在 PATH 里可以进入SDK 目录\emulator下运行.\emulator.exe -avd MauiTest到这里MAUI 创建虚拟安卓设备的链路基本走通了。4. 避坑我与镜像源搏斗时踩过的坑照着上面的步骤能解决问题但实际操作中还有不少细节会让人再次崩溃。下面这些都是我真实遇到过的问题专门整理出来当参考。4.1 修改了源还是无法安装卡在“Accept? (y/N)”换了镜像源之后sdkmanager --list正常了但安装时仍然网络异常。后来发现这不是源的问题而是cmdline-tools版本过旧对新的仓库清单协议支持不完整。解决方法是使用最新版命令行工具。镜像站通常也有对应的commandlinetools下载目录地址结构类似于https://mirrors.tuna.tsinghua.edu.cn/AndroidSDK/commandline-tools/latest/commandlinetools-win-11076708_latest.zip解压后要把里面的cmdline-tools文件夹放到SDK 根目录下并保证最终路径是SDK\cmdline-tools\latest\bin\sdkmanager.bat。注意目录层级解压出来的是cmdline-tools默认名称可能自带版本号需要手动改成latest否则工具会识别不了路径。这条目录层级问题我一开始没注意把工具丢到SDK\cmdline-tools-latest结果 SDK 管理器一直报 “The operation was interrupted”。折腾半天才反应过来是路径结构不对。4.2 虚拟设备只能选 x86 或 x86_64 吗很多人第一次创建 AVD 时会纠结系统镜像架构。用sdkmanager --list可以看到大量镜像比如arm64-v8a、x86_64。如果是 Windows 或 macOS 的 Intel 机器优先选x86_64Apple Silicon 芯片的 Mac 上选arm64-v8a。盲目装arm64-v8a在 x86 宿主上模拟器要么无法启动要么启动后效率极低。反过来也一样。判断当前 CPU 架构Windows 直接在任务管理器里就能看到macOS 可以用uname -m查看。4.3 模拟器启动黑屏或窗口一闪而过这个问题跟网络异常已经没有关系但经常出现在“好不容易解决网络问题”之后。模拟器窗口一闪而过多半是缺少硬件加速。现代 Android 模拟器依赖 Windows Hypervisor Platform 或 Intel HAXM 之类的能力。MAUI 开发机上常驻的 Docker、其他虚拟机软件会和 Hyper-V 抢占资源。处理步骤很简单Windows 功能里开启“Windows 虚拟机监控程序平台”确认 BIOS 已经开启虚拟化运行emulator -accel-check查看加速状态如果输出显示HAXM is not installed说明没有装加速器。但注意开启 Hyper-V 后通常不能再装 HAXM。两者并存容易起冲突。大多数情况下开启 Windows 自带虚拟机监控程序平台就够用了。首次启动模拟器时黑屏时间会比较长我遇到过长则七八分钟的。不要一看到黑屏就以为失败了耐心等一会儿很有可能只是系统镜像首次冷启动慢。4.4 常见问题速查表问题现象常见原因处理办法sdkmanager --list超时仓库源访问慢修改仓库 URL 为镜像地址安装时卡在下载 502镜像同步延时或缓存不一致清理%LOCALAPPDATA%\Android\Sdk\.temp后重试许可协议反复提示未接受所有协议使用 yesavdmanager提示找不到系统镜像镜像版本与 CPU 架构不匹配检查sdkmanager --list中对应的镜像标识模拟器启动后闪退硬件加速未启用开启 Windows 虚拟机监控程序平台MAUI 构建时警告 API level 不匹配项目和 SDK 平台版本不一致安装项目对应的platforms;android-XX5. 最后再分享一个小经验如果你还在用“删掉重试”这种办法跟网络异常搏斗我的建议是先把仓库源切到清华镜像然后重新验证sdkmanager --list。这一步如果通了后面所有组件的安装基本都是水到渠成。镜像源听起来像是什么高深操作实际上就改动一行配置风险极小就算不改 MAUI 项目本身它对后续其他 Android 开发工作也有帮助。我自己的开发机现在仍保留着这套镜像配置。原因很简单它稳定、省心尤其是在创建虚拟设备这种需要下载大体积系统镜像的场景下节省的时间非常可观。如果你按这篇文章处理完之后依然碰到其他报错不要慌优先看日志里有没有 URL 地址把那个地址和镜像站里的对应目录比对一下大多数问题都能找到答案。