若要开始在 Windows、macOS 或 Linux 上开发本机跨平台 .NET MAUI 应用，请按照 安装 步骤安装最新的 Visual Studio Code。
先决条件
若要生成、签名和部署适用于 iOS 和 Mac Catalyst 的 .NET MAUI 应用，需要：
- 与 Xcode 兼容的 Mac。 有关详细信息，请参阅 Apple 的最低要求文档。
- Xcode 的特定版本，具体取决于你使用的 .NET MAUI 版本。 有关信息，请参阅发行版本。
-
Apple ID 和付费 Apple 开发人员计划注册。 需要 Apple ID 才能将应用部署到设备，以及将应用提交到 Apple Store。
安装 Visual Studio Code
若要创建 .NET MAUI 应用，需要下载最新版本的 Visual Studio Code：
安装 Visual Studio Code。 有关如何安装 Visual Studio Code 的详细说明，请参阅 windows上的 Visual Studio Code 、macOS上的 Visual Studio Code ，以及 linux上的 Visual Studio Code 。
安装 .NET MAUI 扩展
在 Visual Studio Code 中创建 .NET MAUI 应用之前，需要安装 .NET MAUI 扩展：
启动 Visual Studio Code。
在 Visual Studio Code 中，导航到 扩展 选项卡并搜索“.NET MAUI”。 然后选择 .NET MAUI 扩展，然后按 安装 按钮进行安装：
.NET MAUI 扩展会自动安装 C# 开发工具包和 C# 扩展，有了它们，.NET MAUI 扩展才能运行。 有关 C# 开发工具包的详细信息，请参阅 适用于 Visual Studio Code 的 C# 开发工具包。
将帐户连接到 C# 开发工具包
使用 C# 开发工具包需要您使用具有有效 Visual Studio 订阅的 Microsoft 帐户登录。
在用于开始使用 .NET MAUI 的“欢迎”选项卡中，按 连接 按钮：
按照提示登录到Microsoft帐户。 有关详细信息，请参阅 登录 C# 开发工具包。
有关 C# 开发工具包许可的详细信息，请参阅 C# 开发工具包常见问题解答。
设置 .NET 环境
需要计算机上安装的 .NET SDK 才能开发 .NET MAUI 应用。 如果计算机上未安装 .NET SDK，在 Windows 上安装它的首选方法是通过 Visual Studio 安装程序。 有关详细信息，请参阅 安装。
或者，若要手动安装 .NET SDK，请执行以下操作：
下载 .NET 安装程序。
通过运行 .NET 安装程序安装 .NET SDK。 有关详细信息，请参阅 在 Windows、Linux 和 macOS上安装 .NET。
提示
在 Linux 上，可以使用 脚本化安装说明安装 .NET SDK。
若要验证是否已安装 .NET SDK，请执行以下操作：
打开终端。
在终端中运行以下命令：
dotnet --version
应会看到已安装的 .NET SDK 版本。
注意
在验证是否已安装 .NET SDK 之前，可能需要重启计算机。
设置 .NET MAUI 环境
需要计算机上安装的 .NET MAUI SDK 才能开发 .NET MAUI 应用。 如果你的计算机上未安装 .NET MAUI SDK，在 Windows 上安装它的首选方法是通过 Visual Studio 安装程序。 有关详细信息，请参阅 安装。
或者，若要手动安装 .NET MAUI SDK，请执行以下操作：
打开终端。
在 Windows 上的终端中运行以下命令：
dotnet workload install maui
在 macOS 上的终端中，运行以下命令：
sudo dotnet workload install maui
在 Linux 上的终端中运行以下命令：
dotnet workload install maui-android
若要验证是否已安装 .NET MAUI SDK，请执行以下操作：
打开终端。
在终端中运行以下命令：
dotnet workload list
在 Windows 和 macOS 上，你应会看到随安装版本列出的 maui 工作负载 ID。 但是，如果你已通过 Windows 上的 Visual Studio 安装程序安装了它，则会列出以下工作负荷 ID：
android
maui-windows
maccatalyst
ios
在 Linux 上，您应该会看到与已安装版本一起列出的 maui-android 工作负载 ID。
若要构建和调试 .NET MAUI 应用，您需要有一个适用于开发计算机操作系统的有效目标平台。 下表列出了每个操作系统上支持的目标平台：
| 你的操作系统 |
受支持的目标平台 |
| Windows |
Windows、Android |
| macOS |
Android、iOS、macOS |
| Linux |
Android |
生成适用于 Android 和 Apple 平台的 .NET MAUI 应用需要执行其他设置和配置。
Android
要在 Android 上通过 Visual Studio Code 进行 .NET MAUI 开发，您需要设置计算机的步骤如下：
下载并安装 Java SDK
若要下载并安装 Java SDK，并配置 Visual Studio Code 以使用它：
下载并安装 Microsoft OpenJDK 17。 有关安装 OpenJDK 的信息，请参阅 安装 OpenJDK的 Microsoft 版本。
或者，可以使用 InstallAndroidDependencies 生成目标来安装 Java SDK（和 Android SDK），而不是手动下载和安装 Java SDK。 有关详细信息，请参阅 使用 InstallAndroidDependencies 目标项。
重要
确保记下 OpenJDK 安装到的位置，因为下一步需要这样做。
确保已通过以下方法之一配置了 OpenJDK 的路径：
设置 JAVA_HOME 环境变量以定义计算机的 Java SDK 路径。 这是建议的方法，该方法在计算机级别定义 Java SDK 路径。
注意
如果通过 MSI 在 Windows 上安装 OpenJDK，则可以选择安装安装程序设置 JAVA_HOME 环境变量。
在 Visual Studio Code 中，在 Windows 上 按 ctrl+SHIFT+P，或在 macOS 上 CMD+SHIFT+P，然后选择 .NET MAUI：配置 Android，然后 选择 Java SDK 位置 在用户/工作区级别设置 Java SDK 路径。
通过将 $(JavaSdkDirectory) MSBuild 属性设置为 OpenJDK 路径，在 .csproj 文件中配置 Java SDK 路径。 这将在项目级别定义 Java SDK 路径。
下载并安装 Android SDK
若要下载并安装 Android SDK，并配置 Visual Studio Code 以使用它：
通过以下方法之一下载并安装 Android SDK：
- 创建新的 .NET MAUI 项目后，下载并安装 Android SDK，然后使用
InstallAndroidDependencies 构建目标，这将帮助设置 Android 环境。 这是建议的方法。 有关详细信息，请参阅 使用 InstallAndroidDependencies 目标项。
- 通过在 Visual Studio中 安装 .NET MAUI 开发工作负载，然后在 Android上创建并运行 .NET MAUI 应用，在 Windows 上下载并安装 Android SDK。 此过程将确保已安装 Android SDK 和 Android 模拟器。
- 通过 Android Studio 下载并安装 Android SDK。 有关详细信息，请参阅 在 developer.android.com 上安装 Android Studio。
- 通过 Linux 上的首选包管理器下载并安装 Android SDK。
确保已通过以下方法之一配置了 Android SDK 的路径：
- 设置
ANDROID_HOME 环境变量以定义计算机的 Android SDK 路径。 这是建议的方法，该方法定义计算机级别的 Android SDK 路径。
- 在 Visual Studio Code 中，在 Windows 上 按 ctrl+Shift+P，或在 macOS 上 CMD+SHIFT+P，然后选择 .NET MAUI：配置 Android，然后 选择 Android SDK 位置 在用户/工作区级别设置 Android SDK 路径。
- 通过将
$(AndroidSdkDirectory) MSBuild 属性设置为 Android SDK 路径，在 .csproj 文件中配置 Android SDK 路径。 这将在项目级别定义 Android SDK 路径。
在 Visual Studio Code 中，通过按 Windows 上的 CTRL+SHIFT+P 或 macOS 上的 cmD+SHIFT+P，然后选择 .NET MAUI：配置 Android，然后 刷新 Android 环境来验证 Android 环境是否正确配置。 必须解决检测到的任何错误：
- 在命令面板中，选择 .NET MAUI：配置 Android，然后依次选择 选择 Android SDK 位置 和 选择 Android SDK 位置，并验证它们是否正确指向各自的安装路径。 在 Windows 上，如果通过 Visual Studio 安装 SDK，OpenJDK 将位于 C：\Program Files\Microsoft，Android SDK 将位于 C：\Program Files （x86）\Android\android-sdk。
- 确保 Android SDK 文件夹具有子文件夹，例如 生成工具、cmdline-tools，以及 平台工具。
- 确保 OpenJDK 文件夹具有子文件夹，例如 bin、库等。
- 确保
ANDROID_HOME 环境变量设置为 Android SDK 路径。
- 确保
JAVA_HOME 环境变量设置为你的 Java SDK 路径。
- 如果尚未接受 Android 许可证，则在具有管理员权限的终端中，导航到 Android SDK 的 cmdline-tools/{version}/bin 文件夹并运行
sdkmanager --licenses，然后按照命令行界面的提示进行操作。
使用 InstallAndroidDependencies 目标
在 Android 上安装 .NET MAUI 项目所需的依赖项的建议方法是运行 InstallAndroidDependencies MSBuild 目标。 如果尚未安装，此目标将为你安装 Android SDK。
在终端中，创建新的 .NET MAUI 项目：
dotnet new maui -n "MyMauiApp"
在终端中，将目录更改为 MyMauiApp，并在指定 InstallAndroidDependencies 生成目标时生成应用：
cd MyMauiApp
dotnet build -t:InstallAndroidDependencies -f:net9.0-android -p:AndroidSdkDirectory="/path/to/sdk" -p:AcceptAndroidSDKLicenses=True
注意
如果提供了 InstallAndroidDependencies MSBuild 属性，则 JavaSdkDirectory MSBuild 目标还可以安装 Java SDK。
在上面的命令中：
-
-p:AndroidSdkDirectory="/path/to/sdk" 将 Android 依赖项安装或更新到指定的绝对路径。 建议的路径是在 Windows 上 %LOCALAPPDATA%/Android/Sdk，在 macOS 上 $HOME/Library/Android/sdk。
-
-p:AcceptAndroidSDKLicenses=True 接受所需的 Android 许可证以便进行开发。
- （可选）
-p:JavaSdkDirectory="/path/to/sdk" 将 Java SDK 安装到指定的绝对路径。
尝试避免使用包含空格或非 ASCII 字符的路径。
下载并安装 Android 模拟器
若要下载并安装运行应用的 Android 模拟器，请执行以下操作：
在终端中，导航到 {YOUR_ANDROID_SDK_FOLDER}/cmdline-tools/{version}/bin/。
在终端中，使用 sdkmanager 命令下载并安装 Android 模拟器：
在 Windows 上运行以下命令：
sdkmanager --install emulator
sdkmanager --install "system-images;android-35;google_apis;x86_64"
在 macOS 上运行以下命令：
./sdkmanager --install emulator
./sdkmanager --install "system-images;android-35;google_apis;arm64-v8a"
注意
上述命令假定 Apple Silicon Mac。 对于 Intel Mac，请将 arm64-v8a 替换为 x86_64。
有关 sdkmanager 命令的详细信息，请参阅 developer.android.com 上的 sdkmanager。
在终端中，使用 avdmanager 命令创建新的 Android 模拟器：
在 Windows 上运行以下命令：
avdmanager create avd -n MyAndroidVirtualDevice-API35 -k "system-images;android-35;google_apis;x86_64"
在 macOS 上运行以下命令：
./avdmanager create avd -n MyAndroidVirtualDevice-API35 -k "system-images;android-35;google_apis;arm64-v8a"
注意
上述命令假定 Apple Silicon Mac。 对于 Intel Mac，请将 arm64-v8a 替换为 x86_64。
有关 avdmanager 命令的详细信息，请参阅 developer.android.com 上的 avdmanager。
iOS 和 macOS
若要使用 Visual Studio Code 在 iOS 和 Mac Catalyst 上设置 Mac for .NET MAUI 开发，请执行以下操作：
安装你使用的 .NET MAUI 版本所需的 Xcode 版本。 有关信息，请参阅发行版本。 可以从 Apple App Store 下载最新的稳定 Xcode 版本。
在终端中，运行以下命令以获取 Xcode 命令行工具：
xcode-select --install
启动 Xcode 并接受任何许可协议。 如果模拟器未开始安装，请进入 Xcode > 设置 > 组件 并安装您选择的模拟器运行环境。
在 Visual Studio Code 中，按 CMD+SHIFT+P，然后选择 .NET MAUI：配置 Apple，再选择 刷新 Apple 环境，以验证 Apple 环境配置是否正确。 必须解决检测到的任何错误：
- 确保已在终端中运行
xcode-select --install。
- 如果收到 Xcode 未找到的错误，请在终端中运行
xcode-select -p，并检查它是否返回 Xcode 安装的路径。
- 打开 Xcode 以确保它正确加载，然后导航到 Xcode > 设置 > 位置，并检查 命令行工具 字段是否指向正确的 Xcode 安装。
故障排除
如果在 Visual Studio Code 中安装 .NET MAUI 扩展时遇到问题，可以通过导航到 输出 窗口（在 Windows 上CTRL+SHIFT+U 或在 macOS 上选择 .NET MAUI）找到有关问题的详细信息。
提供反馈
若要从 Visual Studio Code 内部提供有关 .NET MAUI 扩展的反馈，请导航到 帮助 > 报告问题 对话框。 然后，请确保选择“Bug 报告”作为 的值，这是一个 下拉列表，“A VS Code 扩展”作为 For 下拉列表的值，“.NET MAUI”作为 扩展 下拉列表的值：
