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 页面就能既美观又可靠。
