若要开始在 Windows、macOS 或 Linux 上开发跨平台的本机 .NET MAUI 应用，请按照安装步骤安装最新的 Visual Studio Code。
先决条件
若要生成、签名和部署适用于 iOS 的 .NET MAUI 应用，需要：
- 与 Xcode 兼容的 Mac。 有关详细信息，请参阅 Apple 的最低要求文档。
- Xcode 的特定版本，具体取决于你使用的 .NET MAUI 版本。 有关信息，请参阅发行版本。
- Apple ID 和付费 Apple 开发人员计划注册。 需要 Apple ID 才能将应用部署到设备，以及将应用提交到 Apple Store。
安装
若要创建 .NET MAUI 应用，需要安装最新的 Visual Studio Code。
在 Visual Studio Code 的“扩展”选项卡中，搜索“.NET MAUI”并安装 .NET MAUI 扩展。 .NET MAUI 扩展会自动安装 C# 开发工具包和 C# 扩展，有了它们，.NET MAUI 扩展才能运行。
注意
.NET MAUI 扩展需要 C# 开发工具包和 C# 扩展。 必须登录 C# 开发工具包才能使用 .NET MAUI 扩展的功能。 有关详细信息，请参阅这篇博客文章，了解有关 C# 开发工具包及其扩展系列的详细信息。
安装 .NET 和 .NET MAUI 工作负载
安装 .NET 8。
在 Windows 上，建议使用 Visual Studio 安装程序来管理 .NET 和 .NET MAUI 工作负载安装。 有关使用 Visual Studio 安装程序的说明，请参阅此处。
在 Linux 上，使用脚本安装说明进行安装。
安装 .NET MAUI 工作负载。
在 Windows 上，除非通过 Visual Studio 安装程序安装，否则请在终端中运行以下命令：
dotnet workload install maui
在 macOS 上，在终端中运行以下命令：
sudo dotnet workload install maui
在 Linux 上，在终端中运行以下命令：
dotnet workload install maui-android
若要在 Visual Studio Code 中调试 .NET MAUI 应用，需要提供一个与开发计算机的操作系统相对应的有效目标平台。 包括无效的目标平台将导致项目无法生成。 可以在应用的项目文件 (.csproj) 中管理目标平台：
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>
| 你的操作系统 |
受支持的目标平台 |
| Windows |
Windows、Android |
| macOS |
Android、iOS、macOS |
| Linux |
Android |
iOS 和 macOS
若要在 Visual Studio Code 中调试到 iOS 或 macOS 目标，请执行以下操作：
- 安装你使用的 .NET MAUI 版本所需的 Xcode 版本。 有关信息，请参阅发行版本。 可以从 Apple App Store 下载最新的稳定 Xcode 版本。
- 在终端中运行
xcode-select --install 以获取 Xcode 命令行工具。
- 打开 Xcode，并确保接受任何许可协议。
Android
若要在 Visual Studio Code 中调试到 Android 目标，请执行以下操作：
- 安装 Microsoft OpenJDK 17。
- 通过以下方法之一安装 Android SDK：
- （推荐）创建新的 .NET MAUI 项目 (
dotnet new maui)，并使用 InstallAndroidDependencies 目标。
- 通过 Visual Studio 安装（仅限 Windows）。
- 通过 Android Studio 安装。
- 在 Linux 上通过首选的包管理器进行安装。
故障排除
为 Visual Studio Code 设置 .NET MAUI 扩展时，可能会遇到问题。 若要查看与扩展相关的错误的详细信息，请导航到“输出”窗口 (CTRL/CMD + Shift + u)，然后在下拉列表中选择“.NET MAUI”。 请参阅以下部分，以帮助解决问题。 如果在执行故障排除步骤后仍遇到问题，请报告问题。
项目创建
在尝试创建新项目时，如果文件资源管理器不断无限循环弹出，则说明不能选择空文件夹。 确认不存在隐藏文件或文件夹，创建新文件夹，或者从命令行使用 dotnet new maui 来创建 .NET MAUI 应用。
使用 InstallAndroidDependencies 目标
.NET 8 具有一个生成目标，可帮助你设置 Android 环境。 在终端中运行以下命令，以配置计算机并设置 Android 环境：
dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory="<AndroidSdkPath>" -p:JavaSdkDirectory="<JavaSdkPath>" -p:AcceptAndroidSDKLicenses=True
在上面的命令中：
AndroidSdkDirectory="<AndroidSdkPath>"：将 Android 依赖项安装或更新到指定的绝对路径。
- Windows：建议的 AndroidSdkPath 为
%LOCALAPPDATA%/Android/Sdk。
- macOS：建议的 AndroidSdkPath 为
$HOME/Library/Android/sdk。
JavaSdkDirectory="<JavaSdkPath>"：将 Java 安装到指定的绝对路径。AcceptAndroidSDKLicenses=True：接受所需的 Android 许可证进行开发。
出现“找不到 Android SDK 或 Java SDK”的错误
- 按 Ctrl/Cmd + Shift + P 打开命令面板，然后搜索
.NET MAUI: Configure Android 命令。 同时选择“设置 Android SDK 路径”和“设置 Android JDK 路径”，并验证它们是否指向每个路径下的安装。
- Android SDK 文件夹应具有像
build-tools、cmdline-tools 和 platform-tools 这样的子文件夹。
- Java OpenJDK 文件夹应具有像
bin、lib 这样的子文件夹。
- 在 Windows 上，如果通过 Visual Studio 进行安装，Java SDK 将位于
C:\Program Files\Microsoft\，而 Android SDK 将位于 C:\Program Files (x86)\Android\android-sdk。
- 将
JAVA_HOME 环境变量设置为有效的 Java OpenJDK 路径。
- 将
ANDROID_HOME 环境变量设置为 Android SDK 路径。
- 检查已安装的 Android 依赖项的最低版本：
- build-tools >= 34.0.0
- cmdline-tools == 11.0
- platforms;android-34*
- .NET 8: platform-tools = 34.0.5
存在 Android 许可证不被接受的错误
在提升的命令提示符或终端中，导航到 Android SDK 的 cmdline-tools/latest/bin/ 文件夹，然后运行 sdkmanager --licenses 并按照 CLI 提示符进行操作。
Android 依赖项无法在解决方案资源管理器中加载，但应用生成正常
这是一个已知问题，在 WIndows 上安装到 %APPDATA% 时就会出现，会在未来的版本中修复此问题。
iOS/Xcode 安装
- 如果出现找不到 Xcode 的错误，请在终端运行
xcode-select --install，然后检查 xcode-select -p 是否指向 Xcode 安装。
- 如果仍遇到问题，请打开 Xcode，以确保其能正确加载。 打开 Xcode 后，导航到“Xcode > Settings > Locations”，并检查“Command Line Tools”字段是否指向了正确的 Xcode。
- 有一个已知的问题是，有时必须生成两次 iOS/macOS 应用才能部署。 即将发布的版本中会修复此缺陷。
调试问题
- 由于多种原因，调试可能无法开始。 如果在“输出”窗口中没有明确的错误，请先仔细检查是否在 Visual Studio Code 中使用 C# 运行配置。
- 如果使用的是旧版 .NET，则 .NET MAUI 应用不支持 C# 调试程序。 可以通过取消选中扩展设置“MAUI”>“配置”>“实验”>“使用 VSDbg”来使用旧版 .NET MAUI 调试配置。
- 可以尝试从终端生成命令行，以查看错误是否与代码或 .NET MAUI 扩展有关。 例如，可以运行
dotnet build -f:net8.0-android 以查看 Android 是否在 Visual Studio Code 外部成功生成。 如果此生成成功，请报告问题
已知限制
- 目前，无法切换 IntelliSense 的目标框架（它将仅为 .csproj 文件中列出的第一个目标框架显示语法突出显示）。 此功能正在开发中。 若要为其他目标（例如 Android 而不是 iOS）获取语法突出显示，可以在项目文件中重新排列目标框架。
- .NET 热重载目前在 C# 开发工具包中为预览版。
请在我们继续构建这一新体验时，关于你希望看到的其他功能向我们提供反馈！
提供反馈
请在提出新问题或建议之前，阅读 C# 开发工具包常见问题解答并检查现有的已知问题。 可以通过“帮助”>“报告问题”对话框从 Visual Studio Code 内部提交建议和问题。 确保选择“扩展”，然后在下拉列表中选择 .NET MAUI 扩展。
