Xamarin Forms构建报Manifest中<queries>元素未识别错误的原因排查

报错提示：unexpected element <queries> found in manifest while building the project
触发报错的Manifest配置片段：

<queries>
    <intent>
      <action android:name="android.intent.action.VIEW" />
      <data android:scheme="smsto" />
    </intent>
</queries>

已知场景：同项目同事可正常构建，单独本地环境报错；原项目targetSdkVersion为29，尝试升级为30后报错仍未消除。

报错核心原理 #

<queries>是Android 11（API Level 30）正式引入的Manifest配置节点，用于声明应用需要获取的软件包可见性权限。版本低于30的Android构建工具链没有内置对该节点的解析规则，扫描Manifest时会将其识别为非法自定义节点，直接抛出解析错误。

本地环境差异导致的常见诱因 #

• 本地安装的Android SDK Build-Tools版本低于30.0.0
  即使项目的targetSdkVersion配置为30，只要构建流程调用的底层编译工具是低于API30版本的，就会在Manifest合并/解析阶段识别不出<queries>节点触发报错。同事构建正常的核心原因是他们本地的Build-Tools版本满足要求，和你本地版本存在差异。
• 本地Xamarin.Android SDK版本过低
  Xamarin.Android的构建插件本身负责做Manifest的前置解析，旧版本插件没有适配API30的Manifest规则，即使系统层的Build-Tools版本符合要求，插件层的解析逻辑依然会把<queries>判定为非法节点。这类问题通常出现在Visual Studio版本跨大版本的场景：你的VS长期未更新，附带的Xamarin.Android SDK版本落后于团队成员的本地环境。
• Nuget包还原出现版本漂移
  本地Nuget缓存损坏、源配置不一致时，还原依赖过程中会拉取和团队配置不一致的旧版Xamarin.Android相关依赖，旧版本依赖内嵌的Manifest合并逻辑不支持<queries>节点，也会触发合并报错。
• Manifest节点嵌套位置不符合规范
  按照Android官方规则，<queries>必须作为<manifest>根节点的直接子节点，和<application>、<uses-permission>节点平级。如果该片段被错误嵌套进<application>或其他子节点内部，部分版本的构建工具会出现识别异常。

排查解决路径 #

• 打开Android SDK管理器，安装30.0.0及以上版本的Build-Tools，确认项目属性中指定的编译用Build-Tools版本不低于30。
• 同步本地Visual Studio版本和团队成员的版本，确保附带的Xamarin.Android SDK版本一致，避免跨大版本VS构建同一项目。
• 清理本地Nuget全局缓存后重新还原项目依赖，校验所有Xamarin.Android相关Nuget包的版本和团队配置无差异。
• 检查<queries>节点的嵌套层级，确认其直接隶属于<manifest>根节点，没有被嵌套到其他配置节点内部。

内容的提问来源于stack exchange，提问作者Vakulenko