Blazor WebAssembly预渲染仅首页可用，刷新其他页面报404如何解决？

问题根源 #

Blazor WebAssembly属于单页应用（SPA），客户端路由由Blazor框架在浏览器端处理。刷新非首页路径（如/counter）时，浏览器会直接向服务器请求该路径，但服务器没有对应物理文件或后端路由，因此返回404错误。预渲染功能需要服务器将所有未匹配的路由请求转发到Blazor的入口页面index.html，确保客户端路由能正常接管并完成预渲染内容的 hydration。

解决方案 #

一、确认Blazor预渲染基础配置 #

先确保项目已正确启用预渲染：

• 托管式项目的Program.cs中已添加预渲染路由配置：

  app.MapRazorComponents<App>()
      .AddInteractiveWebAssemblyRenderMode()
      .AddAdditionalAssemblies(typeof(Client._Imports).Assembly);
  

• 客户端项目App.razor的Router组件配置正常，包含Found和NotFound模板，确保路由匹配逻辑正确。

二、配置服务器回退路由（核心步骤） #

根据部署的服务器类型，添加对应配置，将所有非静态资源、非API的请求转发到index.html：

1. Kestrel（ASP.NET Core托管）

在服务器项目Program.cs中，将SPA回退中间件添加到路由配置之后：

// 先配置Blazor预渲染路由
app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(Client._Imports).Assembly);

// 所有未匹配的请求转发到index.html
app.MapFallbackToFile("index.html");

注意：此中间件必须放在所有其他路由（如API路由）配置之后，避免拦截正常的后端请求。

2. IIS

在项目根目录创建web.config，添加URL重写规则：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Blazor SPA Fallback" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
            <add input="{REQUEST_URI}" pattern="^/(api)" negate="true" /> <!-- 排除API路由 -->
          </conditions>
          <action type="Rewrite" url="/index.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

3. Apache

在项目根目录创建.htaccess文件，添加重写规则：

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} !^/api/
    RewriteRule . /index.html [L]
</IfModule>

4. Nginx

在Nginx的服务器配置块中添加：

location / {
    try_files $uri $uri/ /index.html;
}

# 若存在API路由，单独配置代理
location /api {
    proxy_pass http://your-api-backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

三、验证效果 #

配置完成后重启服务器，刷新/counter等非首页路径：

• 查看页面源代码，能看到服务器预渲染的Counter组件静态HTML，说明预渲染生效
• 页面加载后交互功能正常，无404错误

排查要点 #

• 确认服务器已部署wwwroot下的所有Blazor静态资源
• 回退路由规则需排除API、静态文件等不需要Blazor处理的路径
• 预渲染中间件需在回退中间件之前配置，确保预渲染逻辑优先执行

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