dotnet-maui-doctor

.NET MAUI Doctor

验证并修复 .NET MAUI 开发环境。所有版本要求均通过 NuGet API 动态发现——绝不硬编码版本。

适用场景

• 设置新的 .NET MAUI 开发环境
• 构建错误提示缺少 SDK、工作负载、JDK 或 Android 组件
• 出现“找不到 Android SDK”“Java 版本”或“找不到 Xcode”等错误
• SDK 或操作系统更新后验证环境状态

不适用场景

• 非 MAUI .NET 项目（请改用标准 .NET SDK 故障排查）
• Xamarin.Forms 应用（工具链和工作负载要求不同）
• 与环境设置无关的应用运行时崩溃
• 应用商店发布或签名问题
• 特定 IDE 的问题（Visual Studio 或 VS Code 配置）

重要提示：.NET 版本时效性

你的训练数据可能包含过时的 .NET 版本信息。.NET 每年 11 月发布一个新的主要版本。请务必检查 releases-index.json（任务 2），以发现最新的受支持主要版本——不要假设训练数据反映了当前版本。例如，如果你了解到的是 .NET 9.0，但发布索引显示 .NET 10.0 处于受支持状态，请使用 .NET 10.0。

输入

• 运行 macOS、Windows 或 Linux 的开发机器
• Shell 访问权限（macOS/Linux 使用 Bash，Windows 使用 PowerShell）
• 用于查询 NuGet API 和下载 SDK 的互联网连接
• 安装 SDK 和工作负载可能需要管理员/sudo 权限
• Bash 前置条件：curl、jq 和 unzip（macOS/Linux）
• PowerShell 前置条件：Invoke-RestMethod 和 System.IO.Compression（Windows 内置）

行为

• 自主运行所有任务
• 每次修复后重新验证
• 持续迭代，直到全部完成或无法采取进一步操作
• 检测到平台后（任务 1），只加载对应平台的参考资料

工作流

任务 1：检测环境

# macOS
sw_vers && uname -m

# Windows
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"

# Linux
cat /etc/os-release && uname -m

检测后，加载对应平台的参考资料：

• macOS：references/platform-requirements-macos.md、references/installation-commands-macos.md、references/troubleshooting-macos.md
• Windows：references/platform-requirements-windows.md、references/installation-commands-windows.md、references/troubleshooting-windows.md
• Linux：references/platform-requirements-linux.md

任务 2：检查 .NET SDK

dotnet --info

将已安装版本与 https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json 中 support-phase 为 "active" 的 latest-sdk 进行比较。

任务 3：检查 MAUI 工作负载

工作负载	macOS	Windows	Linux
maui	必需	必需	❌ 使用 maui-android
maui-android	别名	别名	必需
android	必需	必需	必需
ios	必需	可选	不适用

任务 4：从 NuGet 发现要求

完整流程请参阅 references/workload-dependencies-discovery.md。

查询 NuGet 工作负载清单 → 提取 WorkloadDependencies.json → 获取：

• jdk.version 范围和 jdk.recommendedVersion
• androidsdk.packages、buildToolsVersion、apiLevel
• xcode.version 范围

任务 5：验证 Java JDK

仅支持 Microsoft OpenJDK。 验证 java -version 输出中是否包含“Microsoft”。检测路径请参阅 references/microsoft-openjdk.md。

使用 WorkloadDependencies.json 推荐的 JDK 版本（jdk.recommendedVersion），并确保其符合 jdk.version 范围。不要硬编码 JDK 版本。

不需要设置 JAVA_HOME。 .NET MAUI 工具会从已知路径自动检测 Microsoft OpenJDK 安装。不要告知用户设置 JAVA_HOME——这没有必要，而且可能导致指向非 Microsoft JDK。

JAVA_HOME 状态	正常？	操作
未设置	✅	无需操作——自动检测可正常工作
设置为 Microsoft JDK	✅	无需操作
设置为非 Microsoft JDK	⚠️	报告为异常——由用户决定取消设置或改为指向其他位置

任务 6：验证 Android SDK

检查 androidsdk.packages、buildToolsVersion、apiLevel（任务 4）。有关 sdkmanager 命令，请参阅 references/installation-commands.md。

任务 7：验证 Xcode（仅限 macOS）

xcodebuild -version

与任务 4 中的 xcode.version 范围进行比较。请参阅 references/installation-commands-macos.md。

任务 8：验证 Windows SDK（仅限 Windows）

Windows SDK 通常作为 .NET MAUI 工作负载或 Visual Studio 的一部分安装。请参阅 references/installation-commands-windows.md。

任务 9：修复

所有命令请参阅 references/installation-commands.md。

关键规则：

• 工作负载：始终使用 --version 标志。切勿使用 workload update 或 workload repair。
• JDK：仅安装 Microsoft OpenJDK。不要设置 JAVA_HOME（会自动检测）。
• Android SDK：使用 sdkmanager（来自 Android SDK 命令行工具）。在 Windows 上使用 sdkmanager.bat。

任务 10：重新验证

每次修复后，都要重新运行相关验证任务。重复此过程，直至所有检查通过。

验证

成功运行后应满足以下条件：

• 已安装 .NET SDK，且与某个有效发行版匹配
• 已安装所有必需的工作负载，且版本一致
• 已检测到 Microsoft OpenJDK（java -version 包含 "Microsoft"）
• 已安装所有必需的 Android SDK 软件包（依据 WorkloadDependencies.json）
• Xcode 版本处于受支持范围内（仅限 macOS）
• 已检测到 Windows SDK（仅限 Windows）

构建验证（推荐）

所有检查通过后，创建并构建一个测试项目，以确认环境确实可用：

TEMP_DIR=$(mktemp -d)
dotnet new maui -o "$TEMP_DIR/MauiTest"
dotnet build "$TEMP_DIR/MauiTest"
rm -rf "$TEMP_DIR"

在 Windows 上，使用 $env:TEMP 或 New-TemporaryFile 获取临时目录。

如果构建成功，则环境已通过验证。如果失败，请根据错误输出排查剩余问题。

运行验证（可选——先询问用户）

成功构建后，询问用户是否要在目标平台上启动应用，以验证端到端流程：

# Replace net10.0 with the current major .NET version
dotnet build -t:Run -f net10.0-android
dotnet build -t:Run -f net10.0-ios        # macOS only
dotnet build -t:Run -f net10.0-maccatalyst # macOS only
dotnet build -t:Run -f net10.0-windows    # Windows only

仅运行与用户的平台和意图相关的目标框架。此步骤会将应用部署到模拟器／仿真器／设备，因此继续操作前请先向用户确认。

常见问题

• maui 与 maui-android 工作负载：在 Linux 上，无法使用 maui 元工作负载，应改用 maui-android。在 macOS／Windows 上，maui 会安装所有平台工作负载。
• workload update／workload repair：切勿使用这些命令。始终使用明确的 --version 标志安装工作负载，以确保版本一致。
• 非 Microsoft JDK：仅支持 Microsoft OpenJDK。即使版本正确，其他发行版（Oracle、Adoptium、Azul）也会导致构建失败。
• 不必要的 JAVA_HOME：不要设置 JAVA_HOME。MAUI 会从已知安装路径自动检测 JDK。如果 JAVA_HOME 指向非 Microsoft JDK（例如 Temurin），请将其报告为异常——它可能会覆盖自动检测结果并导致失败。是否取消设置由用户决定。
• 硬编码版本：切勿硬编码 SDK、工作负载或依赖项版本。始终从 NuGet API 动态获取（参见任务 4）。
• Windows 上的 Android SDK sdkmanager：在 Windows 上使用 sdkmanager.bat，而不是 sdkmanager。
• 过时的训练数据：大模型训练数据可能包含过时的 .NET 版本信息。始终检查 releases-index.json，以确定当前有效的发行版。

参考资料

• references/workload-dependencies-discovery.md — NuGet API 发现流程
• references/microsoft-openjdk.md — JDK 检测路径、标识、JAVA_HOME
• references/installation-commands.md — .NET 工作负载、Android SDK（sdkmanager）
• references/troubleshooting.md — 常见错误及解决方案
• references/platform-requirements-{platform}.md — 特定平台的要求
• references/installation-commands-{platform}.md — 特定平台的安装命令
• references/troubleshooting-{platform}.md — 特定平台的故障排除

官方文档：

• .NET MAUI 安装
• .NET SDK 下载
• Microsoft OpenJDK
• Android SDK 命令行工具
• Xcode 下载