如何修改ASP.NET Core Web应用的启动错误页面？

当然可以自定义这个启动错误页！默认的“An error occurred while starting the application.”页面确实不够友好，而且正如你所说，常规的错误处理文档里没覆盖这个场景——因为启动阶段的异常发生在中间件管道构建完成之前，没法用UseExceptionHandler这类常规中间件处理，得用专门的配置方式：

核心思路 #

通过CaptureStartupErrors让WebHost捕获启动异常，然后配置一个简化的请求处理管道，在启动失败时返回自定义的友好页面。

具体实现步骤 #

1. 配置捕获启动错误

在你的Program.cs中，构建WebHost时添加CaptureStartupErrors(true)，这会让WebHost捕获启动过程中的异常，而不是直接崩溃退出：

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        // 捕获启动阶段的错误
        .CaptureStartupErrors(true)
        // 生产环境关闭详细错误（避免泄露敏感信息）
        .UseSetting(WebHostDefaults.DetailedErrorsKey, "false")
        // 先配置启动失败时的处理逻辑
        .Configure(app =>
        {
            // 这个回调会在启动失败时被调用，接管所有请求
            app.Run(async context =>
            {
                context.Response.StatusCode = StatusCodes.Status500InternalServerError;
                context.Response.ContentType = "text/html";
                
                // 这里可以直接返回自定义HTML内容，或者读取静态文件
                await context.Response.WriteAsync(@"
                    <!DOCTYPE html>
                    <html>
                    <head>
                        <title>网站维护中</title>
                        <style>
                            body { font-family: 'Segoe UI', Arial; max-width: 600px; margin: 2rem auto; padding: 0 1rem; }
                            h1 { color: #dc3545; }
                            p { font-size: 1.1rem; line-height: 1.6; }
                        </style>
                    </head>
                    <body>
                        <h1>抱歉，网站暂时无法访问</h1>
                        <p>我们正在处理启动故障，请稍后再试。如果问题持续，请联系管理员。</p>
                    </body>
                    </html>");
            });
        })
        .UseStartup<Startup>();

2. （可选）使用静态错误页面

如果不想把HTML硬编码在代码里，可以把自定义错误页放在wwwroot目录下（比如命名为startup-error.html），然后修改Configure里的逻辑读取这个文件：

app.Run(async context =>
{
    context.Response.StatusCode = StatusCodes.Status500InternalServerError;
    context.Response.ContentType = "text/html";
    
    var errorPagePath = Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "startup-error.html");
    if (File.Exists(errorPagePath))
    {
        var errorContent = await File.ReadAllTextAsync(errorPagePath);
        await context.Response.WriteAsync(errorContent);
    }
    else
    {
        //  fallback内容
        await context.Response.WriteAsync("<h1>启动失败</h1><p>网站暂时无法访问，请稍后重试。</p>");
    }
});

3. ASP.NET Core 3.0+ 顶级语句写法

如果你的项目用了顶级语句（Top-level statements），代码结构会略有不同，但核心逻辑一致：

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureWebHostDefaults(webBuilder =>
{
    webBuilder.CaptureStartupErrors(true);
    webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "false");
    webBuilder.Configure(app =>
    {
        app.Run(async context =>
        {
            // 自定义错误内容逻辑
        });
    });
    webBuilder.UseStartup<Startup>();
});

var app = builder.Build();

// 常规中间件配置...

app.Run();

关键注意事项 #

• CaptureStartupErrors(true)是核心：它确保启动错误不会直接终止应用，而是让我们配置的简化管道处理请求。
• 生产环境务必关闭DetailedErrors：避免泄露服务器或代码的敏感信息。
• 这个配置只会处理启动阶段的错误，运行时的异常还是用常规的UseExceptionHandler中间件处理。

内容的提问来源于stack exchange，提问作者John-Luke Laue