排查已知问题 - .NET MAUI | Microsoft Learn

找不到 .NET MAUI 工作负载

有两个选项可用于安装 .NET MAUI 工作负载：

Windows 上的 Visual Studio 可以为每个工作负荷包安装 .msi 文件。


    dotnet workload install

命令。

在 Windows 上，如果在通过 Visual Studio 安装程序安装 .NET MAUI 后运行 dotnet workload install ，Visual Studio 可以进入无法找到 .NET MAUI 工作负载的状态。然后，你将收到生成错误，指示你安装 .NET MAUI 工作负载，并且可能会进入无法修复或重新安装工作负载的状态。有关此问题的详细信息，请参阅 CLI 和 VS 无法很好地运行。

Windows

Windows 上此问题的解决方案是通过 CLI 卸载 .NET MAUI 工作负载，卸载控制面板中的任何 .NET SDK，并在 Visual Studio 中卸载 .NET MAUI 工作负载。这可以通过以下过程来实现：

如果曾经使用过命令，


    dotnet workload install

请运行


    dotnet workload uninstall maui

。

从控制面板卸载任何独立的 .NET SDK 安装程序。这些名称将类似于


    Microsoft .NET SDK 6.0.300

。

在 Visual Studio 的每个实例中，卸载 .NET 多平台应用 UI 开发和 .NET 桌面开发 Visual Studio 工作负载。

然后，检查是否有其他 .msi 文件需要通过运行以下命令卸载：

reg query HKLM\SOFTWARE\Microsoft\Windows\currentversion\uninstall\ -s -f manifest
此命令 reg query 将列出计算机上仍安装的 .NET 6+ SDK，例如：
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\currentversion\uninstall\{EEC1BB5F-3391-43C2-810E-42D78ADF3140}
    InstallSource    REG_SZ    C:\ProgramData\Microsoft\VisualStudio\Packages\Microsoft.MacCatalyst.Manifest-6.0.300,version=125.179.40883,chip=x64,productarch=neutral\
    DisplayName    REG_SZ    Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.300
如果收到类似的输出，应复制每个包的 GUID，并使用 msiexec 命令卸载包：
msiexec /x {EEC1BB5F-3391-43C2-810E-42D78ADF3140} /q IGNOREDEPENDENCIES=ALL
然后，应继续执行命令， reg query 直到它不返回任何结果。 发生这种情况并卸载所有 .NET 6+ SDK 后，还应考虑删除以下文件夹：
C:\Program Files\dotnet\sdk-manifests
C:\Program Files\dotnet\metadata
C:\Program Files\dotnet\packs
C:\Program Files\dotnet\library-packs
C:\Program Files\dotnet\template-packs
C:\Program Files\dotnet\sdk\6.* 或 C:\Program Files\dotnet\sdk\7.*
C:\Program Files\dotnet\host\fxr\6.* 或 C:\Program Files\dotnet\host\fxr\7.*
完成此过程后，应能够通过 Visual Studio 或安装所选的 .NET SDK 版本并运行 dotnet workload install maui 命令来重新安装 .NET MAUI。
Visual Studio for Mac的安装程序和更新程序使用dotnet workload install命令安装 .NET MAUI .pkg 文件。
由于无法卸载 .pkg 文件，因此在 Mac 上卸载工作负载的最简单方法是运行以下命令以删除指定的文件夹：
rm -r ~/.dotnet/
sudo rm -r /usr/local/share/dotnet/
执行这些命令后，应能够通过Visual Studio for Mac或安装所选的 .NET SDK 版本并运行dotnet workload install maui命令来重新安装 .NET MAUI。
平台版本不存在
如果尝试编译项目并收到类似于以下文本的错误，Visual Studio 可能无法解析所需的工作负载：
平台版本不适用于一个或多个目标框架，即使它们指定了一个平台：net6.0-android、net6.0-ios、net6.0-maccatalyst
此问题通常是由于安装了 x86 和 x64 SDK，并且正在使用 x86 版本。 Visual Studio 和 .NET MAUI 需要 x64 .NET SDK。 如果操作系统具有先解析 x86 SDK 的系统范围 PATH 变量，则需要通过从 PATH 变量中删除 x86 .NET SDK 或升级 x64 .NET SDK 以便先解析来解决此问题。 有关排查 x86 与 x64 SDK 解析问题的详细信息，请参阅 在 Windows 上安装 .NET - 故障排除。
类型或命名空间“Default”不存在
使用 Contacts API 时，可能会看到以下与 iOS 和 macOS 相关的错误：
The type or namespace name 'Default' does not exist in the namespace 'Contacts' (are you missing an assembly reference?)
iOS 和 macOS 平台包含名为 的 Contacts根命名空间。 此冲突会导致具有 命名空间（包含 Contacts 类型）的那些平台Microsoft.Maui.ApplicationModel.Communication发生冲突。 命名空间 Microsoft.Maui.ApplicationModel.Communication 由 <ImplicitUsings> 项目文件中的设置自动导入。
若要编写同时针对 iOS 和 macOS 进行编译的代码，请完全限定类型 Contacts 。 或者，在代码文件顶部提供一个 using 指令来映射 Communication 命名空间：
using Communication = Microsoft.Maui.ApplicationModel.Communication;
// Code that uses the namespace:
var contact = await Communication.Contacts.Default.PickContactAsync();
Xcode 当前未安装或找不到
安装 Xcode 命令行工具后，使用 xcode-select --installVisual Studio for Mac在尝试生成面向 iOS 或 Mac Catalyst 的 .NET MAUI 应用时，可能会显示“当前未安装 Xcode 或找不到 Xcode”消息。 在此方案中，检查也从 App Store安装了 Xcode。 然后，启动 Xcode 并转到“Xcode > 首选项>位置>”“命令行工具”，如果下拉列表为空，检查。 如果为空，请选择下拉列表，然后选择 Xcode 命令行工具的位置。 然后关闭 Xcode 并重启Visual Studio for Mac。
找不到有效的 Xcode 应用捆绑包
如果收到错误“在'/Library/Developer/CommandLineTools'处找不到有效的 Xcode 应用包”，则尝试生成面向 iOS 或 Mac Catalyst 的 .NET MAUI 应用时，应尝试 Xcode 中所述的解决方案当前未安装或找不到。 如果仍然无法访问 “Xcode > 首选项 > 位置 > ”“命令行工具 ”下拉列表，请运行以下命令：
sudo xcode-select --reset