Aurelia+.NET Core SPA自定义401/404/500错误页最优方案咨询

嘿，针对你这个基于Aurelia + .NET Core的SPA自定义错误页面需求，我来分享下经过实践验证的最优方案——毕竟这种直接输地址触发服务器端错误的场景，确实得前后端配合好才能完美解决。咱们分服务器端（.NET Core）和客户端（Aurelia）两部分来拆解：

这部分是核心，因为用户直接输入地址时请求先到服务器，必须在这里先拦截错误并返回正确的响应。

1. 中间件顺序与基础配置 #

中间件的执行顺序至关重要，必须遵循「静态文件 → 错误处理 → 路由 → 认证授权 → 端点 → SPA fallback」的逻辑。以.NET 6+的Program.cs为例：

var builder = WebApplication.CreateBuilder(args);

// 注册服务
builder.Services.AddControllersWithViews();
builder.Services.AddSpaStaticFiles(configuration =>
{
    configuration.RootPath = "ClientApp/dist"; // 替换成你的Aurelia构建输出目录
});

var app = builder.Build();

// 环境区分的错误处理
if (!app.Environment.IsDevelopment())
{
    // 保留原始HTTP状态码的同时，执行错误页面逻辑
    app.UseStatusCodePagesWithReExecute("/error/{0}");
    // 捕获未处理的服务器异常，跳转到500错误页
    app.UseExceptionHandler("/error/500");
}
else
{
    // 开发环境保留详细错误信息，方便调试
    app.UseDeveloperExceptionPage();
}

// 先处理静态资源请求，不存在的静态文件直接返回404，不fallback到SPA
app.UseStaticFiles();
if (!app.Environment.IsDevelopment())
{
    app.UseSpaStaticFiles();
}

app.UseRouting();
app.UseAuthorization();

// 映射API接口
app.MapControllers();

// SPA路由fallback：仅当请求不是API/静态文件时，返回SPA入口页
app.MapFallbackToFile("/index.html");

app.Run();

2. 错误页面Controller实现 #

创建一个ErrorController，用来接收错误状态码并返回SPA入口页，让Aurelia接管错误页面的渲染（保证UI风格统一）：

public class ErrorController : Controller
{
    [Route("/error/{statusCode}")]
    public IActionResult Error(int statusCode)
    {
        // 将状态码传递给SPA，方便客户端渲染对应内容
        ViewData["StatusCode"] = statusCode;
        return File("~/index.html", "text/html");
    }
}

3. 分错误类型的细节处理 #

• 404错误：覆盖两种场景：
  • 静态资源不存在：UseStaticFiles直接返回404，触发/error/404路由返回SPA页面；
  • 用户直接输入不存在的SPA路由：MapFallbackToFile返回index.html，Aurelia加载后匹配fallback路由显示404页面。
• 500错误：UseExceptionHandler捕获所有未处理的服务器异常，自动跳转到/error/500。
• 401错误：在认证配置中区分页面请求和API请求：

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Events = new JwtBearerEvents
        {
            OnChallenge = context =>
            {
                // 页面请求重定向到401错误页，API请求返回JSON错误信息
                if (!context.HttpContext.Request.Path.StartsWithSegments("/api"))
                {
                    context.Response.Redirect("/error/401");
                }
                else
                {
                    context.Response.StatusCode = 401;
                    context.Response.ContentType = "application/json";
                    return context.Response.WriteAsync(System.Text.Json.JsonSerializer.Serialize(new { message = "未授权访问" }));
                }
                return Task.CompletedTask;
            }
        };
    });

服务器端返回index.html后，Aurelia加载完成，需要处理路由错误和API请求错误：

1. 路由配置添加Fallback规则 #

在Aurelia的路由配置中，添加fallback路由匹配所有未定义的路由，同时配置专门的错误页面路由：

// src/router.ts 或你的路由配置文件
import { RouterConfiguration, Router } from 'aurelia-router';

export class App {
  router: Router;

  configureRouter(config: RouterConfiguration, router: Router) {
    config.title = '我的SPA应用';
    config.map([
      // 你的业务路由
      { route: '', redirect: 'home' },
      { route: 'home', moduleId: 'views/home', title: '首页' },
      // 错误页面路由
      { route: 'error/:statusCode', moduleId: 'views/error', title: '错误页面' },
      // Fallback路由，匹配所有未定义的路由，默认显示404
      { route: '*', moduleId: 'views/error', settings: { statusCode: 404 } }
    ]);
    this.router = router;
  }
}

2. 错误页面组件实现 #

创建error.html和error.ts组件，根据状态码渲染不同的错误内容：

<!-- src/views/error.html -->
<template>
  <div class="error-container">
    <h1 class="error-code">${statusCode}</h1>
    <p class="error-message">${getErrorMessage()}</p>
    <button class="back-btn" click.delegate="navigateToHome()">返回首页</button>
  </div>
</template>

// src/views/error.ts
import { Router, RouteConfig } from 'aurelia-router';
import { inject } from 'aurelia-framework';

@inject(Router)
export class Error {
  statusCode: number;
  private router: Router;

  constructor(router: Router) {
    this.router = router;
  }

  activate(params: any, routeConfig: RouteConfig) {
    // 优先取URL参数中的状态码，其次是路由配置的默认值
    this.statusCode = params.statusCode || routeConfig.settings.statusCode || 404;
  }

  getErrorMessage(): string {
    switch(this.statusCode) {
      case 401:
        return "抱歉，你没有权限访问此页面，请先登录。";
      case 404:
        return "哎呀，你访问的页面不存在！";
      case 500:
        return "服务器内部出错了，请稍后再试。";
      default:
        return "发生了未知错误，请联系管理员。";
    }
  }

  navigateToHome(): void {
    this.router.navigateToRoute('home');
  }
}

3. HTTP拦截器处理API错误 #

针对SPA内部发起的API请求，添加拦截器捕获401/500错误并跳转到对应页面：

// src/services/http-interceptor.ts
import { HttpResponseInterceptor, HttpResponseMessage, HttpRequestMessage } from 'aurelia-fetch-client';
import { autoinject } from 'aurelia-framework';
import { Router } from 'aurelia-router';

@autoinject
export class ErrorInterceptor implements HttpResponseInterceptor {
  constructor(private router: Router) {}

  async response(response: HttpResponseMessage): Promise<HttpResponseMessage> {
    if (response.status === 401) {
      await this.router.navigateToRoute('error', { statusCode: 401 });
    } else if (response.status === 500) {
      await this.router.navigateToRoute('error', { statusCode: 500 });
    }
    return response;
  }
}

// 在main.ts中注册拦截器
import { HttpClient } from 'aurelia-fetch-client';
import { ErrorInterceptor } from './services/http-interceptor';

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .developmentLogging();

  const httpClient = aurelia.container.get(HttpClient);
  httpClient.configure(config => {
    config
      .withBaseUrl('/api/')
      .withInterceptor(new ErrorInterceptor());
  });

  aurelia.start().then(() => aurelia.setRoot());
}

• 全场景覆盖：既处理了服务器端初始请求的错误，又覆盖了SPA加载后的路由和API错误；
• 状态码合规：使用UseStatusCodePagesWithReExecute保留原始HTTP状态码，对SEO友好；
• UI一致性：所有错误页面都由Aurelia渲染，避免服务器端页面和SPA风格脱节；
• 资源区分清晰：静态资源请求和SPA路由请求分开处理，不会出现不存在的图片返回SPA页面的问题。

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