.NET MAUI AppShell通过XAML注册路由后导航异常问题排查

1. 相对路由异常与绝对路由清空导航栈问题 #

问题原因 #

在AppShell.xaml中注册路由时，路由会与TabBar/Flyout的层级结构绑定。如果你的页面是作为全局路由（直接在<Shell.Route>中注册）而非嵌套在对应Tab的<ShellContent>下，原有的相对路由会因不符合Shell的层级导航规则抛出异常；而使用///绝对路由时，会直接替换根导航栈，导致返回时无历史页面可退，直接退出应用。

修复方案 #

• 嵌套路由到对应Tab：将需要在Tab内导航的页面注册到Tab的子路由中，示例：

<TabBar>
    <Tab Title="首页" Route="home">
        <ShellContent ContentTemplate="{DataTemplate local:HomePage}" Route="homepage"/>
        <!-- 将AddAddressPage注册为Home Tab的子路由 -->
        <ShellContent ContentTemplate="{DataTemplate local:AddAddressPage}" Route="addaddress"/>
    </Tab>
</TabBar>

此时使用相对路由即可正常导航：

await Shell.Current.GoToAsync("addaddress");

• 保留全局路由但调整导航方式：如果页面需要全局访问，使用绝对路由时，可通过Navigation.PushAsync替代Shell路由导航，避免清空导航栈；或者在注册全局路由时，确保目标页面被包裹在导航栈容器中。

2. Newtonsoft.Json序列化错误问题 #

问题原因 #

该问题与路由注册方式无关，核心是传递的参数JSON格式与接收类型不匹配：你传递的是JSON数组，但接收属性的类型是单个Professional对象，导致反序列化失败。

修复方案 #

• 检查导航参数的传递代码：如果传递的是List<Professional>集合，确保接收端的属性类型也是List<Professional>：

// 接收页面代码
[QueryProperty(nameof(Professionals), "professionals")]
public List<Professional> Professionals { get; set; }

• 若确实需要传递单个对象，检查序列化代码是否误将单个对象序列化为数组，比如避免使用JsonConvert.SerializeObject(new List<Professional>{ singlePro })这类写法，直接序列化单个对象即可。

是否需要回到代码后台注册路由？ #

不一定，XAML注册路由完全可以正常工作，关键在于是否匹配你的应用导航结构：

• 优先选择XAML注册：如果你的页面大多属于TabBar/Flyout的子页面，XAML注册能直观体现导航层级，减少代码维护成本。
• 适合代码注册的场景：如果你的应用存在大量全局页面、动态注册路由的需求，或需要更灵活的路由层级控制，代码后台注册会更合适。

核心差异原因 #

代码后台注册的路由默认是全局路由，路由之间无层级关联；而XAML注册的路由会与TabBar/Flyout的视觉结构绑定，形成层级化路由关系。你之前的相对路由失效，本质是路由层级结构从“扁平全局”变为“层级嵌套”后，原有路由路径不再适配新的结构。

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