Blazor 自定义 404 Not Found 页面教程-C#.Net教程-PHP中文网

Blazor 自定义 404 Not Found 页面教程

煙雲

发布： 2025-12-24 10:15:33

原创

800人浏览过

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

blazor 自定义 404 not found 页面教程

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：

AI Content Detector

Writer推出的AI内容检测工具

119

查看详情

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 连接正常，否则路由切换可能卡住