Blazor 自定义 404 Not Found 页面教程

Blazor 自定义 404 页面需在 App.razor 中配置 Router 的 NotFound 模板，并为 WebAssembly 部署启用 UseEndpoints.MapFallbackToFile(“index.html”)，确保客户端路由接管未匹配路径。

Blazor 应用默认不自动处理客户端路由未匹配的情况，所以直接访问一个不存在的路径（比如 /nonexistent）时，页面可能空白、报错，或回退到服务器 404 —— 这不是我们想要的用户体验。要实现真正友好的自定义 404 页面，关键在于：在 Blazor 的客户端路由层拦截未匹配路径，并渲染专属的 NotFound 内容。

在 App.razor 中配置 NotFound 模板

这是最核心且必须的一步。Blazor Router 组件支持内置的 NotFound 参数，用于指定当没有路由匹配时显示的内容。

打开 App.razor（通常位于项目根目录），确保 Router 组件包含 NotFound 块：

<Router AppAssembly="@typeof(App).Assembly">     <Found>         <RouteView RouteData="@context" DefaultLayout="@typeof(MainLayout)" />         <FocusOnNavigate RouteData="@context" Selector="h1" />     </Found>     <NotFound>         <PageTitle> 页面未找到 </PageTitle>         <div class="page-not-found">             <h1>404 – 页面不存在 </h1>             <p> 抱歉，您访问的地址可能已更改或尚未创建。</p>             <a href="/" class="btn btn-primary"> 返回首页 </a>         </div>     </NotFound> </Router>

✅ 注意：这个 NotFound 块只对 客户端路由匹配失败 生效（即 Blazor WebAssembly 或 Blazor Server 的 前端 路由），它不会替代服务器端的 HTTP 404 响应。

确保静态文件中间件正确处理“兜底”请求（Blazor WebAssembly 必做）

对于 Blazor WebAssembly（托管或独立部署），浏览器 发起的每个 URL 请求都会先到达服务器（如 Nginx、IIS 或 .NET 的静态文件中间件）。如果服务器找不到对应物理文件，需将请求“重写”回 index.html，让 Blazor 客户端路由接管 —— 否则直接 404。

在 Program.cs（.NET 6+）中，确保静态文件中间件启用了 TryFallbackToPage：

app.UseStaticFiles(); app.UseRouting(); <p>// ✅ 关键：让未匹配的请求回退到 index.html，交由 Blazor 路由处理 app.UseEndpoints(endpoints => { endpoints.MapFallbackToFile("index.html"); });

? 如果你用的是 Azure Static Web Apps、Vercel 或 GitHub Pages，需查阅对应平台的重写规则文档（例如 _redirects 文件或 staticwebapp.config.json），确保所有非资源路径都指向 /index.html。

可选：封装为独立组件提升复用性

把 404 内容抽成单独组件（如 NotFound.razor），更清晰也便于复用：

@* NotFound.razor *@ @page "/404" @inject NavigationManager Navigation <PageTitle> 页面未找到 </PageTitle><div class="not-found-container"><h1>? 404 Not Found</h1><p> 您访问的页面不存在。</p><button @onclick="GoHome" class="btn"> 回到首页 </button></div><p>@code {private void GoHome() => Navigation.NavigateTo("/"); }

然后在 App.razor 的 NotFound 区域直接引用它：

<NotFound>     <NotFound /> </NotFound>

验证与调试小贴士

• 不要在浏览器地址栏直接输入带查询参数的非法路径（如 /abc?x=1）来测试——确保是纯路径不匹配，比如 /this-page-does-not-exist
• 打开浏览器开发者工具 → Network 标签，确认该请求状态码是 200 OK（因为是客户端路由），而不是 404（那是服务器拦下来的）
• 若看到白屏 + 控制台报错 Unhandled exception rendering component，检查 NotFound 块内是否误用了 @page 指令或引入了未注入的服务
• Blazor Server 用户还需确认 SignalR 连接正常，否则路由切换可能卡住

基本上就这些。不需要改 Web.config、不用写中间件过滤器、也不用依赖 JavaScript —— Blazor 原生的 Router.NotFound 就是为这事设计的。重点是配对好客户端路由兜底和服务器静态文件重写，404 页面就能既美观又可靠。