.NET MAUI 环境配置技巧

对于国内小伙伴在配置 .net maui 时遇到的问题，本教程旨在为大家提供一些指导。

01

基础组件部分

.NET SDK 安装

建议安装最新的 .NET SDK。

下载地址 https://www./link/61340e853c1b55df76945afcbe5fcadb

安装 .NET MAUI

安装 .NET MAUI 后，通过 workload 添加 .NET MAUI 的库。.NET workload 可以在 .NET SDK 的基础上安装，安装不同应用场景的支持，如 .NET MAUI，Blazor 等。您可以通过命令行使用 workload。

dotnet workload install maui

注意

1. Linux 或 macOS 需要管理员权限，因此需要 sudo。

2. 有些朋友喜欢使用 Visual Studio 2025 一站式安装完成，本指南更偏向一步步调整。

3. .NET 7 仍在 RC 阶段，发布后会同步更新。

.NET MAUI 大约每 2-3 周会有一个版本更新，因此建议大家执行：

dotnet workload update maui

您可以通过执行以下命令检查 .NET MAUI 的版本：

dotnet workload list

02

Android 环境设定

在某些地区下载 Android SDK 和模拟器可能存在问题，这里提供一些解决办法。

JDK 安装

安卓环境依赖于 JDK，微软已将原来的 Adoption OpenJDK 升级到 Microsoft OpenJDK 11。

您可以通过 https://www./link/060d6e6b635a8b27ff90e4ef041c2ae9 针对 Windows/macOS/Linux 开发平台安装最新的 Microsoft OpenJDK 版本，并配置好 Java_HOME 和 PATH。

在 macOS/Linux 下，JAVA_HOME 和 PATH 的配置如下：

export JAVA_HOME="{你的 Java 安装路径}/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

在 Windows 下 Path 的配置如下：

Android SDK 安装

在 Visual Studio 2025 安装过程中会安装 Android Command line tools 和 Android SDK 的最新版本，这是最理想的情况，但如果遇到网络安装问题，可以参考以下步骤逐步安装。

Android SDK 离线版本下载地址：

链接: https://www./link/5a460d084470e30fa2ef883c10b34ad5

配置 Android SDK 在您的开发环境下，创建 SDK 的存放目录（示例创建目录为 Android/sdk），在该目录下创建以下文件夹。

注意

这里提供的 offline Android SDK 包括 31、32、33 分别对应 Android 12、Android 12.1、Android 13，建议大家都下载安装好。

文件夹介绍 在您的开发环境下，创建 SDK 的存放目录（示例创建目录为 Android/sdk），在该目录下创建以下文件夹：

a

/ build-tools - 编译工具

可以设定不同版本的编译工具

在该目录下，创建以下子目录：

build-toolsr31(对应系统).zip 解压后 重命名为 /31.0.0

build-toolsr32(对应系统).zip 解压后 重命名为 /32.1.0.rc1

build-toolsr33(对应系统).zip 解压后 重命名为 /33.0.0

b

/ cmdline-tools - 命令行工具

命令行文件

基于不同平台解压，重命名为 7.0，将所有文件直接放在 cmdline-tools 文件夹内。

c

/ emulator - 模拟器可执行文件

直接基于您的平台解压放置该文件夹内即可。

请务必记得一点，需要将 package.xml 授权文件放进去，否则您将无法从 Visual Studio 中开启模拟器。

d

/ platform-tools - 平台相关的命令行工具

直接根据平台解压完成即可。

e

/ platforms - android sdk

直接解压文件：

platform-31_r01.zip 解压后重命名为 android-31

platform-32_r01.zip 解压后重命名为 android-32

platform-33_r02.zip 解压后重命名为 android-33

f

/ system-images - 模拟器镜像

这个解决的是可以帮您构建离线镜像，这里我提供了 Google API 的 x86_64 和 arm64 位的镜像。

如 Android 13 的模拟器对应的就是我的 33 文件夹。

在该目录下，创建 android-33，继续创建该文件夹的子文件夹 google_apis，并根据平台的架构 x86_64 或者 arm64_v8a 创建对应的子文件夹，如我是 apple silion，就是 arm64_v8a。

g

/ patcher

创建子文件夹 v4，解压 zip 包把文件放置在 v4 文件夹内，并将 package.xml 同时放置在 v4 文件夹。

您也可以安装 WSA 作为安卓的模拟环境：

https://www./link/33a1fa551ec50395a7a5e2d76ced7f37

模拟器运行，如果您是 X86_64 架构，请开启 Intel HAXM：

https://www./link/1841038227852628f1d604c0211494a6

03

iOS 环境设定

最新的 Xcode 是需要安装的（因为 Xcode 14 刚发布，.NET MAUI 还没有完整支持，请使用 Xcode 13.4.1）。

下载 Xcode 13.4.1 链接: https://www./link/025d5dcf6672b592a16f4533d4249bd8

macOS 支持多 Xcode 的开发环境，如图：

安装完 Xcode 后记得配置好 Visual Studio 的路径。

也可以通过命令行设定默认的 Xcode，这里建议选择默认为 Xcode 13.4.1：

sudo xcode-select -s Xcode.app(Xcode 13.4.1)

把环境变量设置好 macOS/Linux 下：

export ANDROID_HOME="/Users/luk/Tools/Android/sdk"
export PATH="$PATH:$ANDROID_HOME/platform-tools"
export PATH="$PATH:$ANDROID_HOME/emulator"
export PATH="$PATH:$ANDROID_HOME/cmdline-tools/7.0/bin"

Windows 下的配置：

关于 Windows Remote 现在 Windows 需要远程连接 macOS 的设备，才能启用模拟器和真机，所以大家必须有一台 Mac 系列的相关设备，这里我建议大家使用 macOS 云端的解决方案，节约一下成本：

https://www./link/0ba7bc92fcd57e337ebb9e74308c811f

还有必须 Windows 和 macOS 上的版本统一，否则会有版本不同步出错的情况。

04

在 VS 设定好相关的路径

在 Visual Studio 2025 设定好 iOS 和 Android 的配置路径这是最后一步。

macOS 路径设定

Xcode 的路径配置 Perferences -> SDK -> Apple

Android 路径设定

Android 的路径配置 Perferences -> SDK -> Android -> Locations

Windows 路径设定

05

小结

.NET MAUI 的配置问题主要出现在 Android 和 iOS 的环境配置上，特别是 Android SDK 会根据地区和网络供应商的设置而变。希望本内容能帮助大家在 .NET MAUI 环境安装时解决遇到的问题。