若要開始在 Windows、macOS 或 Linux 上開發原生、跨平臺 .NET MAUI 應用程式，請遵循 安裝步驟來安裝最新的 Visual Studio Code。
必要條件
若要建置、簽署及部署適用於 iOS 的 .NET MAUI 應用程式，您需要：
安裝
若要建立 .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 9。
在 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>net9.0-android;net9.0-ios;net9.0-maccatalyst</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.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 9 的組建目標可協助您設定Android環境。 在終端機中執行下列命令，以設定您的電腦並設定 Android 環境：
dotnet build -t:InstallAndroidDependencies -f:net9.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 9：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 中使用 C# 執行組態。
- 如果您使用舊版 .NET，則 .NET MAUI 應用程式不支援 C# 調試程式。 您可以取消核取延伸模組設定MAUI設定>實驗>性使用 VSDbg，以使用舊版 .NET MAUI > 偵錯組態。
- 您可以從終端機嘗試命令行組建，以查看錯誤是否使用您的程式代碼或 .NET MAUI 擴充功能。 例如，您可以執行
dotnet build -f:net9.0-android 以查看 Android 組建是否在 Visual Studio Code 外部成功。 如果此組建成功，請 回報問題
已知的限制
- 目前，您無法切換 IntelliSense 的目標架構（它只會針對 .csproj 檔案中列出的第一個目標架構顯示語法醒目提示）。 這項功能正在進行中。 若要取得其他目標的語法醒目提示（例如 Android 而非 iOS），您可以在項目檔中重新排序目標架構。
- .NET 熱重新載入 目前在 C# 開發工具包中處於預覽狀態。
請在 我們繼續建置這項新體驗時，給我們提供您想要查看的其他功能的意見 反應！
提供意見反應
請先閱讀 C# 開發工具包常見問題， 並檢查現有的 已知問題 ，再提出新的問題或建議。 您可以透過 [說明 > 報告問題] 對話框，從Visual StudioCode內部提出建議和問題 。 請確定您選取 [擴充功能]，然後在下拉式清單中選取 .NET MAUI 延伸模組。
