已发布Blazor WebAssembly应用API调用跳转至页面而非API控制器

架构老林

2026-8-28

根因说明

Blazor WASM托管部署到Azure App Service时API请求返回index.html，本质是SPA路由兜底规则优先级高于API路由匹配逻辑，未命中API处理逻辑的请求被直接重写到静态首页。本地Release模式运行正常已排除代码逻辑、数据库连接相关问题，故障点全部在部署配置、中间件顺序层面。

排查与修复步骤

按优先级从高到低依次排查：

检查Server项目中间件注册顺序
打开Server项目的Program.cs（.NET 6+）或Startup.cs（.NET 5及以下），确认中间件顺序严格符合要求，API路由映射必须放在SPA兜底回退规则之前。
正确的最小配置示例：

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseWebAssemblyDebugging();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseBlazorFrameworkFiles();
app.UseStaticFiles();
app.UseRouting();

// 先映射API控制器
app.MapControllers();
// 最后配置SPA兜底，顺序不能调换
app.MapFallbackToFile("index.html");

app.Run();

若将MapFallbackToFile写在MapControllers之前，所有未精确匹配静态资源的请求都会直接返回index.html，API逻辑完全不会触发。

检查发布目标是否选择正确
Blazor WASM 托管模式必须以Server项目为发布入口，Client项目的产出会在构建时自动打包到Server项目的wwwroot目录。如果发布时误选Client项目作为目标，部署到Azure的就是纯静态站点，没有.NET运行时承载API逻辑，所有/api路径的请求都会触发静态站的路由回退，返回index.html。
验证方式：进入Azure App Service门户的「高级工具」打开Kudu调试站点，进入site/wwwroot目录，若根目录不存在Server项目对应的dll文件，即可确认发布目标选错，重新选择Server项目发布即可。

检查Windows部署下的web.config重写规则
如果使用Windows计划部署App Service，IIS的URL重写规则可能默认拦截所有路径回退到index.html，需要手动排除API路径。在Server项目根目录新建web.config，配置重写规则跳过/api前缀的请求，示例配置：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\替换为你的Server项目dll名.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" />
      <rewrite>
        <rules>
          <rule name="BypassApiForSpa" stopProcessing="true">
            <match url="^api/.*" />
            <action type="None" />
          </rule>
          <rule name="SpaFallback" stopProcessing="true">
            <match url=".*" />
            <conditions logicalGrouping="MatchAll">
              <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
              <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
            </conditions>
            <action type="Rewrite" url="/index.html" />
          </rule>
        </rules>
      </rewrite>
    </system.webServer>
  </location>
</configuration>

右键该文件选择「属性」，将「复制到输出目录」设置为「如果较新则复制」，重新发布即可生效。

控制器路由校验（低概率）
确认ProjectController的路由特性配置正确，类上标注[Route("api/[controller]")]，接口方法标注对应HTTP谓词特性（如[HttpGet("GetAll")]），不存在发布环境下的配置转换覆盖路由前缀的情况，本地Release正常的情况下该问题概率极低。

验证方式

修复完成重新发布后，直接在浏览器访问https://{你的站点名}.azurewebsites.net/api/Project/GetAll，若返回预期JSON数据而非HTML源码，说明API路由已恢复正常，客户端调用即可正常工作。

内容的提问来源于stack exchange，提问作者Barry de Roode