企业官网建设流程全解析

创建虚拟安卓设备一直是很多 .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 Studio，SDK 也可能在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_url=https\://dl.google.com/android/repository/repository2-3.xml

如果没有看到显式的repo_url，可以找到call "%java_exe%"那一行，在其前面追加一行JAVA_OPTS设定：

set JAVA_OPTS=%JAVA_OPTS% -Dandroid.sdk.repository.url=https://mirrors.tuna.tsinghua.edu.cn/AndroidSDK/repository/repository2-3.xml

注意：在批处理脚本里，原本的 URL 中冒号被写成了\:，这是为了防止冒号被解析成盘符路径。新加的这段如果直接写冒号，也可能被批处理误判。稳妥做法是沿用同样的转义格式：

set JAVA_OPTS=%JAVA_OPTS% -Dandroid.sdk.repository.url=https\://mirrors.tuna.tsinghua.edu.cn/AndroidSDK/repository/repository2-3.xml

macOS 和 Linux 下，对应文件是cmdline-tools/latest/bin/sdkmanager。用编辑器打开，找到CLASSPATH相关部分，新增一行：

JAVA_OPTS="$JAVA_OPTS -Dandroid.sdk.repository.url=https://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。然后创建 AVD：

avdmanager 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_64；Apple 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 常见问题速查表

5. 最后再分享一个小经验

如果你还在用“删掉重试”这种办法跟网络异常搏斗，我的建议是先把仓库源切到清华镜像，然后重新验证sdkmanager --list。这一步如果通了，后面所有组件的安装基本都是水到渠成。镜像源听起来像是什么高深操作，实际上就改动一行配置，风险极小，就算不改 MAUI 项目本身，它对后续其他 Android 开发工作也有帮助。

我自己的开发机现在仍保留着这套镜像配置。原因很简单：它稳定、省心，尤其是在创建虚拟设备这种需要下载大体积系统镜像的场景下，节省的时间非常可观。如果你按这篇文章处理完之后，依然碰到其他报错，不要慌，优先看日志里有没有 URL 地址，把那个地址和镜像站里的对应目录比对一下，大多数问题都能找到答案。