ASP.NET Core+Vue项目API返回HTML而非JSON的排查求助

核心问题定位 #

前端请求API返回HTML而非JSON，本质是请求路径未命中ASP.NET Core的API控制器，导致后端返回默认错误页面或SPA入口页面。Swagger能正常调用说明API逻辑本身没问题，问题出在路由配置、前端请求路径、跨域或SPA路由冲突上。

逐步排查与解决步骤 #

1. 核对API路由配置 #

确保控制器的路由注解完全正确：

• 控制器类必须同时标注 [ApiController] 和路由前缀，示例代码：

[ApiController]
[Route("api/[controller]")]
public class ComputerComponentController : ControllerBase
{
    [HttpGet]
    public IActionResult GetComponents()
    {
        var data = // 你的计算逻辑
        return Ok(data);
    }
}

• 对照Swagger显示的API路径（比如/api/ComputerComponent），前端请求必须完全匹配这个路径，不能少前缀或拼写错误。

2. 修正前端请求路径与跨域配置 #

• 前端请求必须使用完整的API路径，别漏了api前缀：

// 错误写法：路径缺失api前缀
axios.get('/ComputerComponent')
// 正确写法：严格匹配API路由
axios.get('/api/ComputerComponent', {
  headers: { 'Accept': 'application/json' }
})

• 如果前后端跨域部署（比如前端在localhost:8080，后端在localhost:5000），必须在ASP.NET Core中配置跨域：

// Program.cs中添加跨域服务
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowVue",
        policy => policy.WithOrigins("http://localhost:8080")
                        .AllowAnyHeader()
                        .AllowAnyMethod());
});

// 启用跨域中间件（注意顺序：在UseRouting之后，UseAuthorization之前）
app.UseCors("AllowVue");

3. 解决SPA路由与API路由的冲突 #

如果Vue项目嵌入在ASP.NET Core中（用UseSpa托管），后端会把未匹配的请求转发到Vue的index.html，导致API请求被误拦截：

• 确保中间件顺序正确，先匹配API路由再处理SPA：

// Program.cs正确顺序
app.UseRouting();
app.UseCors("AllowVue");
app.UseAuthorization();

// 先处理API控制器路由
app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
});

// 最后处理SPA路由
app.UseSpa(spa =>
{
    spa.Options.SourcePath = "ClientApp";
    if (builder.Environment.IsDevelopment())
    {
        spa.UseVueCli(npmScript: "serve");
    }
});

4. 验证请求头与JSON格式化配置 #

• 前端请求必须明确指定Accept: application/json，避免后端返回其他格式：

axios.get('/api/ComputerComponent', {
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
})

• 确保ASP.NET Core没有移除JSON格式化器：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 可自定义JSON序列化规则（可选）
    });

5. 查看后端日志定位请求流向 #

启用路由调试日志，确认请求是否真的命中了API控制器：

• 在appsettings.Development.json中添加日志配置：

{
  "Logging": {
    "LogLevel": {
      "Microsoft.AspNetCore.Routing": "Debug"
    }
  }
}

• 运行后端，查看控制台日志，就能清楚看到请求是被路由到了API控制器，还是被转发到了静态文件/错误页面。

快速验证技巧 #

1. 直接在浏览器地址栏访问API路径（比如http://localhost:5000/api/ComputerComponent），如果返回JSON，说明后端没问题，问题在前端请求；如果返回HTML，说明后端路由配置有问题。
2. 用Postman测试API，排除Vue框架的影响，确认API本身是否正常返回JSON。

内容的提问来源于stack exchange，提问作者Davyd Anysymov