跟着前两篇把 Blazor 的组件基础写过一遍之后你应该已经能做出来会响应点击的按钮、能加载数据的列表组件了。但真要把页面串成一套能用的系统迟早会撞上两个绕不开的问题每个页面顶部的导航菜单要不要重复写十遍浏览器地址栏里的 URL 到底是怎么和页面对应起来的这篇快速入门三我就专门把布局和路由这两块一次性讲透。布局解决的是“页面公共骨架谁来画”路由解决的是“URL 进来之后谁上场”两者配合起来你的 Blazor 应用才算真正有了可用的导航体系。1. 组件写完了接下来必须面对的两个问题页面怎么拼、怎么跳1.1 布局是“壳”路由是“导航牌”先厘清一个概念在 Blazor 里页面本身也是组件。所谓“页面”就是一个带有路由模板的组件。那么问题来了——每个页面组件都只描述自己的内容部分导航栏、侧边栏、页脚这些每个页面都要出现的东西难道要复制到每一个组件里这就是布局存在的价值。布局好比毛坯房里的承重墙和公共管道你只管贴自己房间的壁纸。把导航菜单、页脚、侧边栏这些公共部分写进布局组件页面组件里只放自己独有的内容布局通过Body这个“插槽”把页面内容接进来渲染。路由则像楼层的导航牌访客在地址栏输入/orders路由系统根据这张“导航牌”找到Orders.razor然后把这个组件塞进布局的Body位置。一个是骨架一个是寻址两者配合起来才是完整的页面体系。很多人初学 Blazor 时喜欢在单个组件里拷贝导航栏短时间能跑页面一多就全是重复 HTML改一个菜单项要动十几个文件。这套路我一开始也走过后面重构时才体会到布局和路由分开设计的分工价值。1.2 默认模板里藏着答案App.razor 和 MainLayout.razor新建一个 Blazor 项目后根目录的App.razor和Shared/MainLayout.razor这两个文件很多人瞄一眼就跳过了实际上 Blazor 的导航体系全在这里。打开App.razor默认大约是这个样子Router AppAssemblytypeof(Program).Assembly Found ContextrouteData RouteView RouteDatarouteData DefaultLayouttypeof(MainLayout) / FocusOnNavigate RouteDatarouteData Selectorh1 / /Found NotFound LayoutView Layouttypeof(MainLayout) p rolealert对不起这个页面不存在。/p /LayoutView /NotFound /Router重点看两个地方。第一个是Router组件它负责扫描程序集里所有带路由的组件把 URL 和组件匹配起来第二个是RouteView它把匹配到的页面渲染出来同时套上DefaultLayout指定的默认布局。也就是说即使你不在页面上写layoutBlazor 也会默认用MainLayout把页面包一层。再打开Shared/MainLayout.razorinherits LayoutComponentBase div classpage div classsidebar NavMenu / /div main Body /main /divBody就是页面内容要填充的插槽这是布局组件最核心的标记。另外注意一个细节模板项目的_Imports.razor里有一行layout MainLayout这就是“默认布局”的真正来源。很多人在某个文件夹里自定义布局时发现页面还是套着 MainLayout就是因为_Imports.razor里的默认布局优先级在起作用这个坑后面会详细说。2. 布局系统的核心机制Body 就是留给页面的插槽2.1 从 LayoutComponentBase 看布局的本质布局组件不是特殊的魔法组件它本质上还是组件只不过继承了一个叫LayoutComponentBase的基类。这个基类只做了一件事暴露一个Body属性类型是RenderFragment。RenderFragment你可以理解成一个“延迟的内容片段”它不立即渲染而是等布局组件渲染到Body所在位置时才把内容输出。看到这里你应该明白了布局组件也是一个普通组件所以它也可以有自己的参数、自己的依赖注入、自己的生命周期方法。这意味着你完全可以在布局里加载用户信息、做权限判断、读取配置再根据这些数据决定渲染什么。这也解释了为什么布局要用组件而不是简单的“母版页”概念——它参与渲染流程而不是静态模板。有个收益容易被忽视因为布局是组件所以布局之间也能嵌套。页面指定一个布局这个布局可以再指定一个更外层的布局最终形成多级包裹结构这在区域后台管理项目里非常实用。2.2 手写一个带侧边栏和面包屑的后台布局不用依赖模板自己动手写一个后台布局并不复杂。在Shared文件夹里新建AdminLayout.razorinherits LayoutComponentBase div classadmin-shell aside classadmin-sidebar ul liNavLink href/dashboard MatchAll数据看板/NavLink/li liNavLink href/orders订单管理/NavLink/li liNavLink href/customers客户管理/NavLink/li /ul /aside main classadmin-main div classadmin-breadcrumbBreadcrumbText/div div classadmin-contentBody/div /main /div code { [Parameter] public string BreadcrumbText { get; set; } ; }这个布局里有侧边栏、有主内容区还预留了一个面包屑参数。要让某个页面使用这个布局最简单的方式是在页面顶部加指令page /dashboard layout AdminLayout h1数据看板/h1或者更省事的方式在某个固定文件夹下新建一个_Imports.razor里面写上layout AdminLayout那么该文件夹下所有页面都会自动套用这个布局不用每个页面都写layout。这里要提醒一句_Imports.razor里的layout是全局默认布局如果你在某个页面里又写了layout SomeLayout页面级别的指令优先级更高会覆盖默认值。布局的样式建议用 Blazor 的 CSS 隔离机制给布局单独建一个AdminLayout.razor.css文件里面只写侧边栏和主区域的样式。为什么推荐隔离因为布局的样式很容易污染页面内的组件一旦用了全局样式表所有页面的子组件都会跟着变排查起来非常头疼。2.3 布局嵌套全局布局和区域布局的组合真实项目里布局往往不止一层。常见结构是整个站点一套外壳顶栏 页脚后台模块再套一套侧边栏。此时你不需要在一个布局里把顶栏、侧边栏、页脚全写完而是用嵌套布局来组合。Blazor 的布局嵌套做法很简单子布局文件的头部同样可以写layout指令。比如后台布局AdminLayout.razor里写上inherits LayoutComponentBase layout MainLayout div classadmin-body aside classadmin-sidebar.../aside div classadmin-contentBody/div /div那么任何使用AdminLayout的页面最终渲染时都会先被MainLayout包一层再包上AdminLayout。渲染顺序是“外层布局先执行”从最外层的Body逐级往里填充直到页面本体内容。这套组合逻辑和页面指定布局是同一套机制理解了Body插槽嵌套布局就不会觉得玄乎。嵌套层级不建议超过三层超过之后调试时心智负担会明显上升。我碰到过四层布局的项目最后为了定位一个样式问题不得不把每一层布局的内容逐个注释掉排查效率很低。两三层足够覆盖绝大多数场景了。2.4 布局样式隔离和资源引用的三个细节用布局做公共骨架时有几个细节特别容易踩第一布局的 CSS 隔离文件只作用于布局自身生成的 DOMBody里的页面组件不受布局 scoped 样式影响。这是设计使然不是 bug。想要统一表格、按钮的全局样式请放到wwwroot/css下的全局样式表里。第二如果布局里引用了 JS 文件比如侧边栏折叠交互建议用inject IJSRuntime并在OnAfterRenderAsync里注册不要直接在布局的head里硬塞脚本标签因为布局 DOM 会被 Blazor 重建直接塞script在某些情况下不会重新执行。第三布局组件的OnInitialized只会在布局实例首次创建时调用一次后续路由切换时如果布局实例复用不会再次触发。下面第五节的排错章节会专门展开这个坑。3. 路由的匹配规则page 背后是一张路由表3.1 page 指令如何变成路由表你可能好奇过页面组件上写page /orders这个字符串到底去了哪里。答案是在编译阶段Razor 编译器会把page指令转换成组件的RouteAttribute。当应用启动时Router组件扫描指定程序集的所有组件把标记了RouteAttribute的组件收集起来构建成一张路由表。所以严格来说Blazor 的路由表是“编译后扫描”出来的而不是开发者在某个文件里手动注册的。这意味着你少写了一个page或者把组件放在了Router扫描不到的程序集里这个页面就静默消失导航过去就是 404。这种“存在但找不到”的问题排查起来比较隐蔽后面会专门讲排查链路。想确认当前应用到底注册了哪些路由可以在服务器日志里开启Microsoft.AspNetCore.Routing的详细级别日志或者直接在页面上用NavigationManager打印当前 URL 看匹配结果。对刚上手的人来说最直接的验证方式是在地址栏手动输入路由地址看页面是否正常渲染。3.2 参数、可选参数和类型约束一个页面可以注册多个page指令也可以通过路由模板接收参数。先看基础写法page /products/{id:int} page /products/{keyword}注意第一行{id:int}的写法这是路由参数加类型约束URL 里id段必须是整数才会匹配这个路由模板如果传了/products/abc整个路由模板不会命中Blazor 会继续尝试其他模板最终全部不匹配才走进NotFound分支。这个特性非常有用可以让路由层先帮你做一次数据校验而不是到页面里再用int.TryParse兜底。除了intBlazor 内置了这些约束约束示例说明bool{active:bool}匹配 true/falsedatetime{date:datetime}匹配有效日期时间decimal{price:decimal}匹配十进制数值double{weight:double}匹配浮点数值float{temp:float}匹配浮点数值guid{id:guid}匹配 GUID 字符串int{id:int}匹配整数long{id:long}匹配长整数自定义约束{code:MyConstraint}自己实现IRouteConstraint参数声明还是用普通的[Parameter]比如code { [Parameter] public int Id { get; set; } }这里有个隐含的类型转换细节路由参数是字符串Blazor 会根据目标属性类型自动转换。因此建议属性类型直接写成int、Guid这样的强类型不要写成string再手动转少一步出错的机会。3.3 通配符、优先级和歧义路由路由模板支持通配符比如page /{*path}可以匹配剩余所有路径段。通配符很适合做“兜底页面”或者“旧链接重定向”但我不建议在没有明确需求时乱用因为它会掩盖很多路由问题。曾经有人在项目里加了/{*path}做兜底之后所有不存在的页面都进入同一个组件导致服务器返回的是 200 而不是 404唯一的 404 页面彻底失效这个设计既不利于 SEO 也不利于排错。路由匹配的优先级规则可以概括为一句话模板越具体优先级越高。静态段优于参数段参数段优于通配符。比如同时存在/user/settings和/user/{id}访问/user/settings时命中的是前者而不是把settings当成id。但一旦没有约束/user/123这种 URL 就可能让两个模板都“沾边”最终按路由表的注册顺序取第一个匹配项这就容易引发歧义。我的建议是参数位置带明确约束比如/user/{id:int}能显著减少歧义静态路径段尽量不和参数段共用前缀必要时用不同的一级路径区分比如/product/list和/product/{id:int}。宁可 URL 稍微长一点也不要让路由匹配靠“运气”。3.4 NotFound 兜底页与加载等待页路由命中不了任何组件时App.razor里的NotFound分支会接管。默认模板里的提示文本太简陋建议至少包含一个返回首页的链接NotFound LayoutView Layouttypeof(MainLayout) div classnot-found h1404/h1 p你要找的页面已经走丢了。/p NavLink href/返回首页/NavLink /div /LayoutView /NotFound注意LayoutView的用法在NotFound分支里没有现成的RouteData所以需要手动指定一个布局让提示页也有统一的公共骨架。如果你希望 404 页面用后台布局换成Layouttypeof(AdminLayout)就行。当你开始用流式渲染时异步组件未加载完会有一个加载状态可以用Suspense包裹等待片段。布局部分如果依赖异步数据也一样会阻塞配一个简单的进度提示能显著提升体验不至于让用户面对白屏干等。4. 页面间的跳转NavLink 和 NavigationManager 的实用细节4.1 为什么用 NavLink 而不是 a 标签在 Blazor 页面里写普通a href/orders虽然可以跳转但它会触发浏览器整页刷新把 Blazor 应用重新加载一遍白白丢掉内存中的状态。正确的做法是用NavLink组件它本质上是经过 Blazor 拦截的链接点击后走内部路由不刷新页面。NavLink还有一个隐藏能力它可以根据当前 URL 自动给链接加高亮样式。默认情况下命中链接会自动加activeclass你也可以自定义NavLink href/orders ActiveClassmenu-highlight订单管理/NavLink很多人不理解Match参数的差异。MatchPrefix是默认行为只要当前 URL 以href开头就算匹配。比如href/orders访问/orders/123时菜单也是高亮的。MatchAll则要求 URL 完全一致才高亮适合“数据看板”这种只有一个入口的页面。如果你发现某个菜单“永远不高亮”或者“一直高亮”但说不清为什么大概率就是Match参数选错了。4.2 命令式跳转NavigationManager.NavigateTo链接能解决用户点击的跳转但代码里需要主动跳转的场景就得靠注入NavigationManagerinject NavigationManager Nav code { private void HandleSave() { // 表单保存成功后跳转 Nav.NavigateTo(/orders); } }saved之后跳转列表页、权限不足时跳转登录页、分页按钮跳转下一页这些场景都会用NavigateTo。主要留意第三个参数forceLoad: trueNav.NavigateTo(/orders, forceLoad: true);默认情况下 Blazor 会尽量在内部完成导航不刷新浏览器。但如果你是从静态页面跳转到 Blazor 应用、或者跳转到外部站点、或者需要让浏览器重新加载一些原生资源就得用forceLoad强制浏览器整页加载。这个参数平时用不上但关键时刻能救命。4.3 页面间传参的三种方式和适用场景页面之间传数据常见三种方式各有各的适用场景不要混用。第一种是路由参数适合传递“资源标识”比如商品 ID、订单号。优点是 URL 可以直接分享刷新页面后参数还在。第二种是查询字符串适合传“筛选条件”或“当前页码”长得像/orders?statuspaidpage2。查询字符串在 Blazor 里读取方式有两种用NavigationManager.Uri自己解析或者在 .NET 7 之后用[SupplyParameterFromQuery]特性绑定属性。第三种是内存共享状态比如注入一个 Scoped 服务页面 A 把复杂对象放进去页面 B 读取。优点是能传复杂的对象缺点是刷新页面后状态就没了所以只适合当前跳转流程内的临时数据。这里给个直接可用的查询字符串绑定示例page /orders using Microsoft.AspNetCore.Components.Web code { [SupplyParameterFromQuery(Name status)] public string? Status { get; set; } [SupplyParameterFromQuery(Name page)] public int Page { get; set; } 1; }页面加载时 Blazor 会自动从 URL 里解析参数填充到属性不用手动写解析代码。要注意的是Page如果 URL 里没传默认值是1该特性和表单绑定互不干扰完全可以并存。我自己的习惯是能用路由参数表达的尽量不要塞查询字符串能用查询字符串表达的尽量不要用内存状态。因为前两种具备“URL 可分享、可刷新、可收藏”的优点只有最后一种在某些浏览器回到上一页的场景下会丢功能稳定性差一个档次。5. 排错经验布局不刷新、路由 404、导航高亮失效的完整排查5.1 布局数据不刷新OnInitialized 只跑一次的陷阱这是一个非常典型的问题布局里根据当前 URL 或用户权限去渲染导航菜单初次进入一切正常但页面切换后菜单没有更新。原因要从布局组件的生命周期说起。多次导航时Blazor 会尽量复用已有的布局实例而不是每次重新创建。这带来一个直接结果OnInitialized方法只在布局实例首次创建时执行一次后续路由切换不再触发。所以如果你把“根据当前路由更新菜单高亮”的逻辑写在OnInitialized里第一次能更新之后就永远停在旧状态。正确做法是把这类逻辑放到OnParametersSet或OnParametersSetAsync里因为每次导航都可能带来新的路由参数OnParametersSet会在每次导航后都执行。写到这里顺手提一个更省心的方案如果高亮逻辑完全依赖NavLink的自动匹配你甚至不需要自己写任何代码让NavLink自己判断即可。只有需要根据 URL 计算“面包屑文案”这类自定义内容时才需要在OnParametersSet里手动解析参数。顺带说下OnAfterRenderAsync也有相同的坑第一次渲染后注册的 JS 事件如果在切换路由后 DOM 被替换事件可能失效。此时要考虑在OnAfterRenderAsync里判断是否firstRender并在适当位置清理和重新注册。5.2 页面一直 404是路由不匹配还是根本没编译进来遇到 404别急着改代码按这个顺序排查大多数问题能快速定位。第一步确认页面文件确实有page指令。看着像废话但实际项目中真有人从别的文件复制组件时漏掉了page。第二步确认组件在Router扫描的程序集里。默认项目扫描的是入口程序集如果你把页面放在另一个类库项目里要在App.razor的Router上加上AdditionalAssemblies。第三步确认参数约束是否匹配。访问/products/abc而路由模板是/products/{id:int}404 是正常行为不是 bug。第四步看浏览器控制台和服务器日志Blazor Server 在这类场景下通常会输出包含Did not match any page directives的警告会直接告诉你哪个 URL 没匹配上。有一种最隐蔽的情况是页面的命名空间被改变了导致组件实际的编译行为异常但不会报错。当你改了一个文件夹的命名空间之后最好整体构建一次确认没有残留旧路由的缓存引用。至于大小写和尾斜杠的问题Blazor 路由匹配默认不区分大小写尾斜杠也做了兼容处理所以通常不是 404 的原因。如果你在部署后发现大小写敏感那大概率是部署服务器层面的重写规则在捣乱不是 Blazor 本身的行为。5.3 NavLink 不高亮或者总是高亮导航高亮的问题本质上就是Match语义没对齐。你可以打开浏览器的开发者工具检查对应链接在路由切换后class属性有没有变化这是最快的定位手段。如果发现class根本没出现先看href是否以/开头。hreforders少了开头斜杠和实际 URL/orders的匹配逻辑会不符合直觉。如果发现class出现了但菜单不对检查是不是用MatchPrefix导致多个菜单同时高亮。访问/orders/123时href/orders和href/orders/123两个NavLink如果用Prefix匹配会同时高亮。此时父级菜单可以用Prefix子级菜单用All或者干脆给子级菜单也写完整的参数路径让匹配关系唯一化。还有一种情况容易被忽略NavLink的href里如果带了查询字符串比如/orders?statuspaid它和高亮匹配的逻辑会有额外限制。非必要不要在导航菜单的链接里写查询字符串筛选条件应该放在页面内部通过按钮触发跳转菜单链接保持简洁才能让高亮逻辑稳定。5.4 布局复用了但页面组件却重新创建这是正常的不少初学者把布局与页面的生命周期混在一起以为页面切换时布局也应该重新初始化。实际恰恰相反布局实例会复用页面组件则根据路由变化创建新实例。这个行为不是问题而是优化——公共骨架不该跟着每个页面反复重建否则菜单闪烁、资源反复加载体验会差很多。理解了这一点前面 5.1 的面包屑不刷新问题就好解释了布局复用了状态自然残留在旧实例上页面新建了每次都会拿到最新的路由数据。所以跨页面共享的信息放在布局里要谨慎别把“只在某个页面有意义”的状态放到布局字段里否则你会体会到什么叫“串页”。6. 把布局和路由用在真实项目里的几条实战建议6.1 布局的粒度别贪多按“外壳 区域”两层规划就够了我见过把顶栏、侧边栏、面包屑、页脚、弹窗容器、通知栏全部塞进一个布局的项目好处是写起来快坏处是任何一个模块想调整都会牵动整个系统。更稳妥的做法是只拆两层第一层是站点级外壳负责顶栏和页脚全站通用第二层是区域级布局负责侧边栏和区域导航只在后台相关页面使用。超过三层就要重新评估是否真的需要那么深的嵌套。路由命名也是一样的道理。别把page写成随便什么路径最好和文件夹结构、菜单层级保持对应。后台模块统一用/admin开头前台页面统一用/portal或根路径开头这样即使项目大了凭 URL 也能判断页面归属哪个模块排查问题的时候会少走很多弯路。6.2 路由参数类型要偏“严”查询参数类型要偏“宽”路由参数直接暴露在 URL 里建议用到int、guid这种强约束让错误 URL 尽早失败而不是进到页面里再处理一堆脏数据。查询参数则相反用户可能会复制粘贴、手输、删除部分内容建议用宽松类型比如string?然后在页面里做默认值和兜底逻辑。这两种参数类型的设计哲学不一样不要混用。另外一个实用技巧路由参数名和属性名尽量保持一致。/products/{id:int}对应[Parameter] public int Id看上去很自然但如果你写page /products/{pid:int}又声明PId属性后面同事接手时就要靠翻代码才能猜出对应关系。保持命名一致是零成本的维护收益。6.3 404 页面要做得像个“页面”而不是一行字默认模板的 404 只是一行“Sorry, there’s nothing at this address.”你上线前最好替换掉。一个合格的 404 页面至少要有三样东西明确的提示文案、返回首页或者上一级的链接、搜索框或者常用入口。这样既对用户友好也在视觉上更像一个真正的产品页面。至于搜索引擎优化记得让服务器对不存在的路径返回正确的 404 状态码这里可以在App.razor的NotFound分支里配合响应状态码设置一起处理。我自己在这块吃过的教训是把 404 页面做成了一个“看起来很像正常页面”的组件结果用户访问到不存在的地址时看不出任何区别还以为进了某个没数据的空页面返回按钮都找不到。所以 404 页面的视觉差异要足够明显别含蓄。6.4 给路由加一层“语义层”用自定义约束约束业务编号如果你的业务编号有自己的格式比如订单号是ORD2025010110001这种固定前缀格式可以考虑写一个自定义路由约束让路由层直接验证格式。实现思路是实现IRouteConstraint接口在Match方法里写格式判断逻辑然后在 Startup 里注册约束。这样/orders/ORD2025010110001正常匹配订单页面而/orders/ABC直接进 404无需在页面里再写业务校验。这个技术不难但对代码组织风格的提升是实打实的。写自定义约束时要留意性能约束解析会参与每个路由请求的匹配所以判断逻辑尽量轻量不要在里面查询数据库。真要校验业务数据是否存在仍然应该在页面加载时异步处理路由约束只负责格式层面的过滤。关于布局和路由我实际操作中最深的体会就是宁可一开始多花半小时把布局的层级和路由的命名规划清楚也不要等组件写到两百个的时候再回来重构到那时候改一个路由路径影响的文件数量会让你怀疑人生。先让Body有地方填内容再考虑样式细节和嵌套层次这样一关一关过基本不会出大问题。
跟着前两篇把 Blazor 的组件基础写过一遍之后你应该已经能做出来会响应点击的按钮、能加载数据的列表组件了。但真要把页面串成一套能用的系统迟早会撞上两个绕不开的问题每个页面顶部的导航菜单要不要重复写十遍浏览器地址栏里的 URL 到底是怎么和页面对应起来的这篇快速入门三我就专门把布局和路由这两块一次性讲透。布局解决的是“页面公共骨架谁来画”路由解决的是“URL 进来之后谁上场”两者配合起来你的 Blazor 应用才算真正有了可用的导航体系。1. 组件写完了接下来必须面对的两个问题页面怎么拼、怎么跳1.1 布局是“壳”路由是“导航牌”先厘清一个概念在 Blazor 里页面本身也是组件。所谓“页面”就是一个带有路由模板的组件。那么问题来了——每个页面组件都只描述自己的内容部分导航栏、侧边栏、页脚这些每个页面都要出现的东西难道要复制到每一个组件里这就是布局存在的价值。布局好比毛坯房里的承重墙和公共管道你只管贴自己房间的壁纸。把导航菜单、页脚、侧边栏这些公共部分写进布局组件页面组件里只放自己独有的内容布局通过Body这个“插槽”把页面内容接进来渲染。路由则像楼层的导航牌访客在地址栏输入/orders路由系统根据这张“导航牌”找到Orders.razor然后把这个组件塞进布局的Body位置。一个是骨架一个是寻址两者配合起来才是完整的页面体系。很多人初学 Blazor 时喜欢在单个组件里拷贝导航栏短时间能跑页面一多就全是重复 HTML改一个菜单项要动十几个文件。这套路我一开始也走过后面重构时才体会到布局和路由分开设计的分工价值。1.2 默认模板里藏着答案App.razor 和 MainLayout.razor新建一个 Blazor 项目后根目录的App.razor和Shared/MainLayout.razor这两个文件很多人瞄一眼就跳过了实际上 Blazor 的导航体系全在这里。打开App.razor默认大约是这个样子Router AppAssemblytypeof(Program).Assembly Found ContextrouteData RouteView RouteDatarouteData DefaultLayouttypeof(MainLayout) / FocusOnNavigate RouteDatarouteData Selectorh1 / /Found NotFound LayoutView Layouttypeof(MainLayout) p rolealert对不起这个页面不存在。/p /LayoutView /NotFound /Router重点看两个地方。第一个是Router组件它负责扫描程序集里所有带路由的组件把 URL 和组件匹配起来第二个是RouteView它把匹配到的页面渲染出来同时套上DefaultLayout指定的默认布局。也就是说即使你不在页面上写layoutBlazor 也会默认用MainLayout把页面包一层。再打开Shared/MainLayout.razorinherits LayoutComponentBase div classpage div classsidebar NavMenu / /div main Body /main /divBody就是页面内容要填充的插槽这是布局组件最核心的标记。另外注意一个细节模板项目的_Imports.razor里有一行layout MainLayout这就是“默认布局”的真正来源。很多人在某个文件夹里自定义布局时发现页面还是套着 MainLayout就是因为_Imports.razor里的默认布局优先级在起作用这个坑后面会详细说。2. 布局系统的核心机制Body 就是留给页面的插槽2.1 从 LayoutComponentBase 看布局的本质布局组件不是特殊的魔法组件它本质上还是组件只不过继承了一个叫LayoutComponentBase的基类。这个基类只做了一件事暴露一个Body属性类型是RenderFragment。RenderFragment你可以理解成一个“延迟的内容片段”它不立即渲染而是等布局组件渲染到Body所在位置时才把内容输出。看到这里你应该明白了布局组件也是一个普通组件所以它也可以有自己的参数、自己的依赖注入、自己的生命周期方法。这意味着你完全可以在布局里加载用户信息、做权限判断、读取配置再根据这些数据决定渲染什么。这也解释了为什么布局要用组件而不是简单的“母版页”概念——它参与渲染流程而不是静态模板。有个收益容易被忽视因为布局是组件所以布局之间也能嵌套。页面指定一个布局这个布局可以再指定一个更外层的布局最终形成多级包裹结构这在区域后台管理项目里非常实用。2.2 手写一个带侧边栏和面包屑的后台布局不用依赖模板自己动手写一个后台布局并不复杂。在Shared文件夹里新建AdminLayout.razorinherits LayoutComponentBase div classadmin-shell aside classadmin-sidebar ul liNavLink href/dashboard MatchAll数据看板/NavLink/li liNavLink href/orders订单管理/NavLink/li liNavLink href/customers客户管理/NavLink/li /ul /aside main classadmin-main div classadmin-breadcrumbBreadcrumbText/div div classadmin-contentBody/div /main /div code { [Parameter] public string BreadcrumbText { get; set; } ; }这个布局里有侧边栏、有主内容区还预留了一个面包屑参数。要让某个页面使用这个布局最简单的方式是在页面顶部加指令page /dashboard layout AdminLayout h1数据看板/h1或者更省事的方式在某个固定文件夹下新建一个_Imports.razor里面写上layout AdminLayout那么该文件夹下所有页面都会自动套用这个布局不用每个页面都写layout。这里要提醒一句_Imports.razor里的layout是全局默认布局如果你在某个页面里又写了layout SomeLayout页面级别的指令优先级更高会覆盖默认值。布局的样式建议用 Blazor 的 CSS 隔离机制给布局单独建一个AdminLayout.razor.css文件里面只写侧边栏和主区域的样式。为什么推荐隔离因为布局的样式很容易污染页面内的组件一旦用了全局样式表所有页面的子组件都会跟着变排查起来非常头疼。2.3 布局嵌套全局布局和区域布局的组合真实项目里布局往往不止一层。常见结构是整个站点一套外壳顶栏 页脚后台模块再套一套侧边栏。此时你不需要在一个布局里把顶栏、侧边栏、页脚全写完而是用嵌套布局来组合。Blazor 的布局嵌套做法很简单子布局文件的头部同样可以写layout指令。比如后台布局AdminLayout.razor里写上inherits LayoutComponentBase layout MainLayout div classadmin-body aside classadmin-sidebar.../aside div classadmin-contentBody/div /div那么任何使用AdminLayout的页面最终渲染时都会先被MainLayout包一层再包上AdminLayout。渲染顺序是“外层布局先执行”从最外层的Body逐级往里填充直到页面本体内容。这套组合逻辑和页面指定布局是同一套机制理解了Body插槽嵌套布局就不会觉得玄乎。嵌套层级不建议超过三层超过之后调试时心智负担会明显上升。我碰到过四层布局的项目最后为了定位一个样式问题不得不把每一层布局的内容逐个注释掉排查效率很低。两三层足够覆盖绝大多数场景了。2.4 布局样式隔离和资源引用的三个细节用布局做公共骨架时有几个细节特别容易踩第一布局的 CSS 隔离文件只作用于布局自身生成的 DOMBody里的页面组件不受布局 scoped 样式影响。这是设计使然不是 bug。想要统一表格、按钮的全局样式请放到wwwroot/css下的全局样式表里。第二如果布局里引用了 JS 文件比如侧边栏折叠交互建议用inject IJSRuntime并在OnAfterRenderAsync里注册不要直接在布局的head里硬塞脚本标签因为布局 DOM 会被 Blazor 重建直接塞script在某些情况下不会重新执行。第三布局组件的OnInitialized只会在布局实例首次创建时调用一次后续路由切换时如果布局实例复用不会再次触发。下面第五节的排错章节会专门展开这个坑。3. 路由的匹配规则page 背后是一张路由表3.1 page 指令如何变成路由表你可能好奇过页面组件上写page /orders这个字符串到底去了哪里。答案是在编译阶段Razor 编译器会把page指令转换成组件的RouteAttribute。当应用启动时Router组件扫描指定程序集的所有组件把标记了RouteAttribute的组件收集起来构建成一张路由表。所以严格来说Blazor 的路由表是“编译后扫描”出来的而不是开发者在某个文件里手动注册的。这意味着你少写了一个page或者把组件放在了Router扫描不到的程序集里这个页面就静默消失导航过去就是 404。这种“存在但找不到”的问题排查起来比较隐蔽后面会专门讲排查链路。想确认当前应用到底注册了哪些路由可以在服务器日志里开启Microsoft.AspNetCore.Routing的详细级别日志或者直接在页面上用NavigationManager打印当前 URL 看匹配结果。对刚上手的人来说最直接的验证方式是在地址栏手动输入路由地址看页面是否正常渲染。3.2 参数、可选参数和类型约束一个页面可以注册多个page指令也可以通过路由模板接收参数。先看基础写法page /products/{id:int} page /products/{keyword}注意第一行{id:int}的写法这是路由参数加类型约束URL 里id段必须是整数才会匹配这个路由模板如果传了/products/abc整个路由模板不会命中Blazor 会继续尝试其他模板最终全部不匹配才走进NotFound分支。这个特性非常有用可以让路由层先帮你做一次数据校验而不是到页面里再用int.TryParse兜底。除了intBlazor 内置了这些约束约束示例说明bool{active:bool}匹配 true/falsedatetime{date:datetime}匹配有效日期时间decimal{price:decimal}匹配十进制数值double{weight:double}匹配浮点数值float{temp:float}匹配浮点数值guid{id:guid}匹配 GUID 字符串int{id:int}匹配整数long{id:long}匹配长整数自定义约束{code:MyConstraint}自己实现IRouteConstraint参数声明还是用普通的[Parameter]比如code { [Parameter] public int Id { get; set; } }这里有个隐含的类型转换细节路由参数是字符串Blazor 会根据目标属性类型自动转换。因此建议属性类型直接写成int、Guid这样的强类型不要写成string再手动转少一步出错的机会。3.3 通配符、优先级和歧义路由路由模板支持通配符比如page /{*path}可以匹配剩余所有路径段。通配符很适合做“兜底页面”或者“旧链接重定向”但我不建议在没有明确需求时乱用因为它会掩盖很多路由问题。曾经有人在项目里加了/{*path}做兜底之后所有不存在的页面都进入同一个组件导致服务器返回的是 200 而不是 404唯一的 404 页面彻底失效这个设计既不利于 SEO 也不利于排错。路由匹配的优先级规则可以概括为一句话模板越具体优先级越高。静态段优于参数段参数段优于通配符。比如同时存在/user/settings和/user/{id}访问/user/settings时命中的是前者而不是把settings当成id。但一旦没有约束/user/123这种 URL 就可能让两个模板都“沾边”最终按路由表的注册顺序取第一个匹配项这就容易引发歧义。我的建议是参数位置带明确约束比如/user/{id:int}能显著减少歧义静态路径段尽量不和参数段共用前缀必要时用不同的一级路径区分比如/product/list和/product/{id:int}。宁可 URL 稍微长一点也不要让路由匹配靠“运气”。3.4 NotFound 兜底页与加载等待页路由命中不了任何组件时App.razor里的NotFound分支会接管。默认模板里的提示文本太简陋建议至少包含一个返回首页的链接NotFound LayoutView Layouttypeof(MainLayout) div classnot-found h1404/h1 p你要找的页面已经走丢了。/p NavLink href/返回首页/NavLink /div /LayoutView /NotFound注意LayoutView的用法在NotFound分支里没有现成的RouteData所以需要手动指定一个布局让提示页也有统一的公共骨架。如果你希望 404 页面用后台布局换成Layouttypeof(AdminLayout)就行。当你开始用流式渲染时异步组件未加载完会有一个加载状态可以用Suspense包裹等待片段。布局部分如果依赖异步数据也一样会阻塞配一个简单的进度提示能显著提升体验不至于让用户面对白屏干等。4. 页面间的跳转NavLink 和 NavigationManager 的实用细节4.1 为什么用 NavLink 而不是 a 标签在 Blazor 页面里写普通a href/orders虽然可以跳转但它会触发浏览器整页刷新把 Blazor 应用重新加载一遍白白丢掉内存中的状态。正确的做法是用NavLink组件它本质上是经过 Blazor 拦截的链接点击后走内部路由不刷新页面。NavLink还有一个隐藏能力它可以根据当前 URL 自动给链接加高亮样式。默认情况下命中链接会自动加activeclass你也可以自定义NavLink href/orders ActiveClassmenu-highlight订单管理/NavLink很多人不理解Match参数的差异。MatchPrefix是默认行为只要当前 URL 以href开头就算匹配。比如href/orders访问/orders/123时菜单也是高亮的。MatchAll则要求 URL 完全一致才高亮适合“数据看板”这种只有一个入口的页面。如果你发现某个菜单“永远不高亮”或者“一直高亮”但说不清为什么大概率就是Match参数选错了。4.2 命令式跳转NavigationManager.NavigateTo链接能解决用户点击的跳转但代码里需要主动跳转的场景就得靠注入NavigationManagerinject NavigationManager Nav code { private void HandleSave() { // 表单保存成功后跳转 Nav.NavigateTo(/orders); } }saved之后跳转列表页、权限不足时跳转登录页、分页按钮跳转下一页这些场景都会用NavigateTo。主要留意第三个参数forceLoad: trueNav.NavigateTo(/orders, forceLoad: true);默认情况下 Blazor 会尽量在内部完成导航不刷新浏览器。但如果你是从静态页面跳转到 Blazor 应用、或者跳转到外部站点、或者需要让浏览器重新加载一些原生资源就得用forceLoad强制浏览器整页加载。这个参数平时用不上但关键时刻能救命。4.3 页面间传参的三种方式和适用场景页面之间传数据常见三种方式各有各的适用场景不要混用。第一种是路由参数适合传递“资源标识”比如商品 ID、订单号。优点是 URL 可以直接分享刷新页面后参数还在。第二种是查询字符串适合传“筛选条件”或“当前页码”长得像/orders?statuspaidpage2。查询字符串在 Blazor 里读取方式有两种用NavigationManager.Uri自己解析或者在 .NET 7 之后用[SupplyParameterFromQuery]特性绑定属性。第三种是内存共享状态比如注入一个 Scoped 服务页面 A 把复杂对象放进去页面 B 读取。优点是能传复杂的对象缺点是刷新页面后状态就没了所以只适合当前跳转流程内的临时数据。这里给个直接可用的查询字符串绑定示例page /orders using Microsoft.AspNetCore.Components.Web code { [SupplyParameterFromQuery(Name status)] public string? Status { get; set; } [SupplyParameterFromQuery(Name page)] public int Page { get; set; } 1; }页面加载时 Blazor 会自动从 URL 里解析参数填充到属性不用手动写解析代码。要注意的是Page如果 URL 里没传默认值是1该特性和表单绑定互不干扰完全可以并存。我自己的习惯是能用路由参数表达的尽量不要塞查询字符串能用查询字符串表达的尽量不要用内存状态。因为前两种具备“URL 可分享、可刷新、可收藏”的优点只有最后一种在某些浏览器回到上一页的场景下会丢功能稳定性差一个档次。5. 排错经验布局不刷新、路由 404、导航高亮失效的完整排查5.1 布局数据不刷新OnInitialized 只跑一次的陷阱这是一个非常典型的问题布局里根据当前 URL 或用户权限去渲染导航菜单初次进入一切正常但页面切换后菜单没有更新。原因要从布局组件的生命周期说起。多次导航时Blazor 会尽量复用已有的布局实例而不是每次重新创建。这带来一个直接结果OnInitialized方法只在布局实例首次创建时执行一次后续路由切换不再触发。所以如果你把“根据当前路由更新菜单高亮”的逻辑写在OnInitialized里第一次能更新之后就永远停在旧状态。正确做法是把这类逻辑放到OnParametersSet或OnParametersSetAsync里因为每次导航都可能带来新的路由参数OnParametersSet会在每次导航后都执行。写到这里顺手提一个更省心的方案如果高亮逻辑完全依赖NavLink的自动匹配你甚至不需要自己写任何代码让NavLink自己判断即可。只有需要根据 URL 计算“面包屑文案”这类自定义内容时才需要在OnParametersSet里手动解析参数。顺带说下OnAfterRenderAsync也有相同的坑第一次渲染后注册的 JS 事件如果在切换路由后 DOM 被替换事件可能失效。此时要考虑在OnAfterRenderAsync里判断是否firstRender并在适当位置清理和重新注册。5.2 页面一直 404是路由不匹配还是根本没编译进来遇到 404别急着改代码按这个顺序排查大多数问题能快速定位。第一步确认页面文件确实有page指令。看着像废话但实际项目中真有人从别的文件复制组件时漏掉了page。第二步确认组件在Router扫描的程序集里。默认项目扫描的是入口程序集如果你把页面放在另一个类库项目里要在App.razor的Router上加上AdditionalAssemblies。第三步确认参数约束是否匹配。访问/products/abc而路由模板是/products/{id:int}404 是正常行为不是 bug。第四步看浏览器控制台和服务器日志Blazor Server 在这类场景下通常会输出包含Did not match any page directives的警告会直接告诉你哪个 URL 没匹配上。有一种最隐蔽的情况是页面的命名空间被改变了导致组件实际的编译行为异常但不会报错。当你改了一个文件夹的命名空间之后最好整体构建一次确认没有残留旧路由的缓存引用。至于大小写和尾斜杠的问题Blazor 路由匹配默认不区分大小写尾斜杠也做了兼容处理所以通常不是 404 的原因。如果你在部署后发现大小写敏感那大概率是部署服务器层面的重写规则在捣乱不是 Blazor 本身的行为。5.3 NavLink 不高亮或者总是高亮导航高亮的问题本质上就是Match语义没对齐。你可以打开浏览器的开发者工具检查对应链接在路由切换后class属性有没有变化这是最快的定位手段。如果发现class根本没出现先看href是否以/开头。hreforders少了开头斜杠和实际 URL/orders的匹配逻辑会不符合直觉。如果发现class出现了但菜单不对检查是不是用MatchPrefix导致多个菜单同时高亮。访问/orders/123时href/orders和href/orders/123两个NavLink如果用Prefix匹配会同时高亮。此时父级菜单可以用Prefix子级菜单用All或者干脆给子级菜单也写完整的参数路径让匹配关系唯一化。还有一种情况容易被忽略NavLink的href里如果带了查询字符串比如/orders?statuspaid它和高亮匹配的逻辑会有额外限制。非必要不要在导航菜单的链接里写查询字符串筛选条件应该放在页面内部通过按钮触发跳转菜单链接保持简洁才能让高亮逻辑稳定。5.4 布局复用了但页面组件却重新创建这是正常的不少初学者把布局与页面的生命周期混在一起以为页面切换时布局也应该重新初始化。实际恰恰相反布局实例会复用页面组件则根据路由变化创建新实例。这个行为不是问题而是优化——公共骨架不该跟着每个页面反复重建否则菜单闪烁、资源反复加载体验会差很多。理解了这一点前面 5.1 的面包屑不刷新问题就好解释了布局复用了状态自然残留在旧实例上页面新建了每次都会拿到最新的路由数据。所以跨页面共享的信息放在布局里要谨慎别把“只在某个页面有意义”的状态放到布局字段里否则你会体会到什么叫“串页”。6. 把布局和路由用在真实项目里的几条实战建议6.1 布局的粒度别贪多按“外壳 区域”两层规划就够了我见过把顶栏、侧边栏、面包屑、页脚、弹窗容器、通知栏全部塞进一个布局的项目好处是写起来快坏处是任何一个模块想调整都会牵动整个系统。更稳妥的做法是只拆两层第一层是站点级外壳负责顶栏和页脚全站通用第二层是区域级布局负责侧边栏和区域导航只在后台相关页面使用。超过三层就要重新评估是否真的需要那么深的嵌套。路由命名也是一样的道理。别把page写成随便什么路径最好和文件夹结构、菜单层级保持对应。后台模块统一用/admin开头前台页面统一用/portal或根路径开头这样即使项目大了凭 URL 也能判断页面归属哪个模块排查问题的时候会少走很多弯路。6.2 路由参数类型要偏“严”查询参数类型要偏“宽”路由参数直接暴露在 URL 里建议用到int、guid这种强约束让错误 URL 尽早失败而不是进到页面里再处理一堆脏数据。查询参数则相反用户可能会复制粘贴、手输、删除部分内容建议用宽松类型比如string?然后在页面里做默认值和兜底逻辑。这两种参数类型的设计哲学不一样不要混用。另外一个实用技巧路由参数名和属性名尽量保持一致。/products/{id:int}对应[Parameter] public int Id看上去很自然但如果你写page /products/{pid:int}又声明PId属性后面同事接手时就要靠翻代码才能猜出对应关系。保持命名一致是零成本的维护收益。6.3 404 页面要做得像个“页面”而不是一行字默认模板的 404 只是一行“Sorry, there’s nothing at this address.”你上线前最好替换掉。一个合格的 404 页面至少要有三样东西明确的提示文案、返回首页或者上一级的链接、搜索框或者常用入口。这样既对用户友好也在视觉上更像一个真正的产品页面。至于搜索引擎优化记得让服务器对不存在的路径返回正确的 404 状态码这里可以在App.razor的NotFound分支里配合响应状态码设置一起处理。我自己在这块吃过的教训是把 404 页面做成了一个“看起来很像正常页面”的组件结果用户访问到不存在的地址时看不出任何区别还以为进了某个没数据的空页面返回按钮都找不到。所以 404 页面的视觉差异要足够明显别含蓄。6.4 给路由加一层“语义层”用自定义约束约束业务编号如果你的业务编号有自己的格式比如订单号是ORD2025010110001这种固定前缀格式可以考虑写一个自定义路由约束让路由层直接验证格式。实现思路是实现IRouteConstraint接口在Match方法里写格式判断逻辑然后在 Startup 里注册约束。这样/orders/ORD2025010110001正常匹配订单页面而/orders/ABC直接进 404无需在页面里再写业务校验。这个技术不难但对代码组织风格的提升是实打实的。写自定义约束时要留意性能约束解析会参与每个路由请求的匹配所以判断逻辑尽量轻量不要在里面查询数据库。真要校验业务数据是否存在仍然应该在页面加载时异步处理路由约束只负责格式层面的过滤。关于布局和路由我实际操作中最深的体会就是宁可一开始多花半小时把布局的层级和路由的命名规划清楚也不要等组件写到两百个的时候再回来重构到那时候改一个路由路径影响的文件数量会让你怀疑人生。先让Body有地方填内容再考虑样式细节和嵌套层次这样一关一关过基本不会出大问题。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
