若要開始在 macOS 上開發原生、跨平臺的 .NET MAUI 應用程式，請遵循 安裝 步驟安裝 Visual Studio 2022 for Mac 17.6。
必要條件
若要建置、簽署及部署適用於 iOS 或 macOS 的 .NET MAUI 應用程式，您也需要：
安裝
若要建立 .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 。
重要
若要搭配 .NET 8 使用 Visual Studio for Mac，請啟用 Visual Studio > 喜好 > 設定其他 > 預覽功能 > ：如果已安裝 [需要重新啟動] 複選框，請使用 .NET 8 SDK。
如果您在公司環境安裝時發生網路問題，請檢閱在防火牆或 Proxy 後方安裝指示。
在防火牆或 Proxy 伺服器後方安裝
若要在防火牆後方安裝 Visual Studio 2022 for Mac，必須讓特定端點可供存取，才能下載軟體所需的工具和更新。 如需設定網路以允許存取必要端點的詳細資訊，請參閱 在防火牆或 Proxy 伺服器後方安裝及使用 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
- 平臺;android-34*
- .NET 7：platform-tools = 33.0.2
- .NET 8：platform-tools = 34.0.5
Android 授權不接受錯誤
在提升許可權的cmdline-tools/latest/bin/命令提示字元或終端機中，流覽至 Android SDK 的資料夾，然後執行 sdkmanager --licenses ，然後遵循 CLI 提示。
我的 Android 相依性不會載入 方案總管，但我的應用程式建置良好
如果您在 Windows 上安裝 至 %APPDATA% ，且將在未來的版本中修正，這是已知問題。
iOS/Xcode 安裝程式
- 如果您收到找不到 Xcode 的錯誤，請在終端機中執行
xcode-select --install ，然後檢查該 xcode-select -p 點指向您的 Xcode 安裝。
- 如果您仍然遇到問題，請開啟 Xcode 本身，以確保其正確載入。 開啟 Xcode 之後，流覽至 [Xcode > 設定 > 位置]，並檢查 [命令行工具] 欄位是否指向正確的 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 StudioCode內部提出建議和問題 。 請確定您選取 [擴充功能]，然後在下拉式清單中選取 .NET MAUI 延伸模組。
