共用方式為

對已知問題進行疑難排解

  • 發行項

本文說明 .NET 多平臺應用程式 UI （.NET MAUI） 的一些已知問題，以及如何解決或解決它們。 .NET MAUI 存放 庫 也會詳細說明一些已知問題。

找不到 .NET MAUI 工作負載

有兩個選項可用來安裝 .NET MAUI 工作負載：

  1. Windows 上的 Visual Studio 可以為每個工作負載套件安裝 .msi 檔案。
  2. dotnet workload install 命令。

在 Windows 上，如果您在透過 Visual Studio 安裝程式安裝 .NET MAUI 之後執行 dotnet workload install ，Visual Studio 可以進入無法找到 .NET MAUI 工作負載的狀態。 您將會收到建置錯誤，告知您安裝 .NET MAUI 工作負載，而且有可能進入無法修復或重新安裝工作負載的狀態。 如需詳細資訊，請參閱 GitHub 問題 dotnet/sdk#22388。

Windows

Windows 上此問題的解決方案是透過 CLI 卸載 .NET MAUI 工作負載、卸載 控制台 中的任何 .NET SDK，以及卸載 Visual Studio 中的 .NET MAUI 工作負載。 這些卸載可透過下列程式來完成：

  1. 如果您曾經使用命令，dotnet workload install請執行 dotnet workload uninstall maui 。
  2. 從 控制台 卸載任何獨立 .NET SDK 安裝程式。 這些安裝程式名稱類似 Microsoft .NET SDK 6.0.300。
  3. 在每個 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 MAUI，或安裝您選擇的 .NET SDK 版本並執行 dotnet workload install maui 命令。

平臺版本不存在

如果您嘗試編譯專案並收到類似下列文字的錯誤，Visual Studio 可能無法解決必要的工作負載：

一或多個目標架構沒有平臺版本，即使已指定平臺：net8.0-android、net8.0-ios、net8.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根命名空間。 此衝突會針對包含 型別的 Microsoft.Maui.ApplicationModel.Communication 命名空間 Contacts ，導致這些平台發生衝突。 命名空間 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-select --install安裝 Xcode 命令行工具之後，當您嘗試建置以 iOS 或 Mac Catalyst 為目標的 .NET MAUI 應用程式時，Visual Studio Code 可能會顯示「目前未安裝 Xcode 或找不到」訊息。 在此案例中，請檢查您也已安裝來自 App Store 的 Xcode。 然後，啟動 Xcode 並移至 [Xcode > 喜好 > 設定位置 > ] 命令行工具 ，並檢查下拉式清單是否空白。 如果是空的，請選取下拉式清單，然後選取 Xcode 命令行工具的位置。 然後關閉 Xcode 並重新啟動 Visual Studio Code。

找不到有效的 Xcode 應用程式套件組合

如果您嘗試建置以 iOS 或 Mac Catalyst 為目標的 .NET MAUI 應用程式時，收到「在 『/Library/Developer/CommandLineTools』 找不到有效的 Xcode 應用程式套件組合」錯誤，請嘗試目前未安裝或找不到 Xcode 中所述的解決方案。 如果您仍然無法存取 Xcode > 喜好 > 設定位置 > 命令列工具 下拉式清單，請執行下列命令：

sudo xcode-select --reset

找不到 Xcode 版本

在某些情況下，在iOS或Mac Catalyst上建置 .NET MAUI 應用程式可能會嘗試使用電腦上不再安裝的 Xcode 版本。 發生這種情況時，您會收到類似下列的錯誤訊息：

xcodebuild: error: SDK "/Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" cannot be located.
xcrun: error: sh -c '/Applications/Xcode_14.1.app/Contents/Developer/usr/bin/xcodebuild -sdk /Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk -find dsymutil 2> /dev/null' failed with exit code 16384: (null) (errno=Invalid argument)
xcrun: error: unable to find utility "dsymutil", not a developer tool or in PATH

建置應用程式時，適用於 iOS 的 .NET 和 .NET for Mac Catalyst 會使用下列程式來判斷要使用的 Xcode 版本：

  1. MD_APPLE_SDK_ROOT如果已設定環境變數，請使用其值。
  2. 如果 ~/Library/Preferences/Xamarin/Settings.plist 檔案存在，請使用其內定義的值。
  3. 使用的值 xcode-select -p。
  4. 使用 /Applications/Xcode.app。

因此，指定計算機上 Xcode 位置的建議方法是將環境變數設定 MD_APPLE_SDK_ROOT 為 Xcode 版本的路徑。 如需詳細資訊，請參閱 使用特定版本的 Xcode 建置。

然後，您可以從您的計算機安全地刪除 ~/Library/Preferences/Xamarin/Settings.plist 。

診斷 Blazor 混合式應用程式中的問題

BlazorWebView 內建記錄可協助您診斷 Blazor 混合式應用程式中的問題。 開啟此記錄有兩個步驟：

  1. 啟用 BlazorWebView 和相關元件來記錄診斷資訊。
  2. 設定記錄器，將記錄檔輸出寫入您可以檢視的位置。

如需詳細資訊，請參閱 診斷 Blazor 混合式應用程式中的問題。

停用映像封裝

為了進行疑難解答，您可以將建置屬性false設定$(EnableMauiImageProcessing)為項目檔中第一個<PropertyGroup>節點，以停用映像資源封裝：

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

停用啟動顯示畫面封裝

為了進行疑難解答，您可以在項目檔的第一個<PropertyGroup>節點中，將組建屬性設定$(EnableSplashScreenProcessing)為 false ，以停用啟動顯示畫面資源產生：

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

停用字型封裝

為了進行疑難解答，您可以在項目檔的第一個<PropertyGroup>節點中，將build屬性設定$(EnableMauiFontProcessing)為 false ，以停用字型資源封裝：

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

停用資產檔案封裝

為了進行疑難解答，您可以在項目檔的第一個<PropertyGroup>節點中，將組建屬性設定$(EnableMauiAssetProcessing)為 false ，以停用資產文件資源封裝：

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

產生空白啟動顯示畫面

為了進行疑難解答，如果您沒有 <MauiSplashScreen> 專案且沒有自定義啟動顯示畫面，則可以產生空白啟動顯示畫面。 若要達成此目的，請在項目檔的第一個<PropertyGroup>節點中將組建屬性設定$(EnableBlankMauiSplashScreen)為 true ：

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

產生空白啟動顯示畫面將會覆寫任何自定義啟動顯示畫面，並會導致 App Store 拒絕。 不過，在測試中，它可以是一種有用的方法，以確保您的應用程式 UI 正確無誤。

重複的影像檔名錯誤

您可能會遇到關於重複映像檔名的建置錯誤：

偵測到一或多個重複的檔名。 所有影像輸出檔名都必須是唯一的。

因為從 .NET 8，.NET MAUI 會檢查 ，以確保沒有重複的影像資源檔名，因此會發生此情況MauiIconMauiImage。

當您在多個資料夾中有相同的檔名，而且在某些情況下，當您在不同的資料夾中有相同擴展名時，就會發生此錯誤。 例如，PNG 檔案會在 Resources/Images/PNG/dotnet_bot.png 和 RESOURCES/Images/SVG/dotnet_bot.svg 的 PNG 檔案發生建置錯誤，因為 SVG 檔案會在建置階段轉換成 PNG 檔案。

如果您在 Include 專案上使用 MauiImage 屬性來包含資料夾中的所有影像，然後同時包含特定的影像檔，也會發生錯誤：

<MauiImage Include="Resources\Images\*" />
<MauiImage Include="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

如果您收到此建置錯誤，可以藉由確保您的項目檔不包含重複的影像來修正。 若要這樣做，請變更參考特定檔案的任何 MauiIcon 或 MauiImage ，以使用 Update 屬性，而不是 Include 屬性：

<MauiImage Include="Resources\Images\*" />
<MauiImage Update="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

如需 MSBuild 專案專案屬性的相關信息，請參閱 Item 元素 （MSBuild）： 屬性和元素。