要开始在 macOS 上开发本机跨平台 .NET MAUI 应用，请按照安装步骤安装 Visual Studio 2022 for Mac 17.6。
先决条件
要生成、签名和部署适用于 iOS 或 macOS 的 .NET MAUI 应用，还需要：
- 与 Xcode 兼容的 Mac。 有关详细信息，请参阅 Apple 的最低要求文档。
- Xcode 的特定版本，具体取决于你使用的 .NET MAUI 版本。 有关信息，请参阅发行版本。
- Apple ID 和付费 Apple 开发人员计划注册。 需要 Apple ID 才能将应用部署到设备，以及将应用提交到 Apple Store。
安装
要创建 .NET MAUI 应用，需要最新的 Visual Studio for Mac：
安装 Visual Studio 2022 for Mac，或修改现有安装，并确保已安装以下工作负载：
- .NET
- .NET MAUI
- Android
- iOS
重要
对于 Visual Studio 2022 for Mac 的新安装，选择 .NET MAUI 工作负载将自动选择 Android 和 iOS 工作负载，而 .NET MAUI 开发当前需要这些工作负载。
通过独立安装程序安装 .NET 8。
安装完 .NET 8 后，在终端中运行 dotnet workload install maui。
重要
若要将 Visual Studio for Mac 与 .NET 8 配合使用，需启用 Visual Studio > 首选项 > 其他 > 预览功能 > 如果已安装则使用 .NET 8 SDK（需要重启）”复选框。
如果在企业环境中安装时遇到网络问题，请查看在有防火墙或代理的情况下安装说明。
在防火墙或代理服务器后面安装
若要在防火墙后面安装 Visual Studio 2022 for Mac，必须将某些终结点设置为可访问，以允许下载所需的工具和更新软件。 有关配置网络以允许访问所需终结点的详细信息，请参阅在防火墙或代理服务器后面安装和使用 Visual Studio for Mac。
注意
Visual Studio Code 中的 .NET MAUI 支持仍处于预览状态。 试用一下并分享你的反馈！
安装 Visual Studio Code 和 .NET MAUI 扩展
安装 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 安装程序的说明，请参阅此处。
安装 .NET MAUI 工作负载。
在 Windows 和 macOS 上，在终端中运行以下命令：
dotnet workload install maui
在 Linux 上，在终端中运行以下命令：
dotnet workload install maui-android
若要在 Visual Studio Code 中调试 .NET MAUI 应用，你需要为开发计算机的操作系统提供有效的目标平台：
| 你的操作系统 |
受支持的目标平台 |
| Windows |
Windows、Android |
| macOS |
Android、iOS、macOS |
| Linux |
Android |
iOS 和 macOS
若要在 Visual Studio Code 中调试到 iOS 或 macOS 目标，请执行以下操作：
- 安装你使用的 .NET MAUI 版本所需的 Xcode 版本。 有关信息，请参阅发行版本。 可以从 Mac App Store 下载最新的稳定 Xcode 版本。
- 在终端中运行
xcode-select --install 以获取 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 扩展时，可能会遇到问题。 如果在执行以下故障排除步骤后仍遇到问题，请报告问题。
项目创建
在尝试创建新项目时，如果文件资源管理器不断无限循环弹出，则说明不能选择空文件夹。 确认不存在隐藏文件或文件夹，创建新文件夹，或者从命令行使用 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 7: platform-tools = 33.0.2
- .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 安装的 xcode-select -p。
- 如果仍遇到问题，请打开 Xcode，以确保其能正确加载。 打开 Xcode 后，导航到“Xcode > Settings > Locations”，并检查“Command Line Tools”字段是否指向了正确的 Xcode。
- 存在一个已知问题，即有时必须生成 iOS/macOS 应用两次才能进行部署。 即将发布的版本中会修复此缺陷。
调试问题
- 由于多种原因，调试可能无法开始。 如果在“输出”窗口中没有明确的错误，请首先复查你是否在 Visual Studio Code 中使用的是“.NET MAUI”运行配置。
- 可以尝试从终端生成命令行，以查看错误是否与代码或 .NET MAUI 扩展有关。 例如，可以运行
dotnet build -f:net8.0-android 以查看 Android 是否在 Visual Studio Code 外部成功生成。 如果此生成成功，请报告问题
已知限制
此扩展仍处于早期预览状态，因此存在许多已知限制。 请在我们继续构建这一新体验时，关于你希望看到的其他功能向我们提供反馈。
- XAML 编辑功能非常轻量 - 你可以获得基本语法突出显示和自动完成功能。 我们正在探索如何在将来的版本中改进 XAML 体验。
- 目前，无法切换 IntelliSense 的目标框架（它将仅为 .csproj 文件中列出的第一个目标框架显示语法突出显示）。 此功能正在开发中。
- 目前不支持 XAML 和 .NET 热重载。
- 此扩展尚未使用最新的 iOS 和 Xcode beta 版进行全面测试。
请在我们继续构建这一新体验时，关于你希望看到的其他功能向我们提供反馈！
提供反馈
请在提出新问题或建议之前，阅读 C# 开发工具包常见问题解答并检查现有的已知问题。 可以通过“帮助”>“报告问题”对话框从 Visual Studio Code 内部提交建议和问题。 确保选择“扩展”，然后在下拉列表中选择 .NET MAUI 扩展。
