ASP.NET Core 6 Razor Pages Index导航跳转index.html异常问题

AI 小北

2026-8-27

问题成因

该异常是Swashbuckle.AspNetCore包与Razor Pages默认路由规则的冲突导致，具体触发逻辑如下：

6.0~6.5版本区间的Swashbuckle.AspNetCore在启用Swagger UI时，会默认将自身入口页index.html注入到ASP.NET Core默认文档匹配列表的最高优先级，同时会干扰Razor Pages标签助手（asp-page）的路由生成逻辑：仅根目录下的Index.cshtml页会被错误识别为静态html文件，生成带.html后缀的路由路径，子目录下的Razor Page（包括子目录下的Index页，如/Files/Index）不受该bug影响。
如果中间件注册顺序错误，将Swagger UI、默认文件中间件放在Razor Pages路由中间件之前，访问根路径时会优先匹配Swagger的静态入口页规则，直接跳转至不存在的/index.html路径，同时会覆盖launchSettings.json中配置的根路径启动规则。
部分低版本包安装时会误在wwwroot目录下生成占位用的index.html文件，也会触发相同的路由优先级冲突。

修复方案

按以下优先级操作，即可完全解决路由异常：

修正中间件与Swagger配置（首选方案）
打开项目根目录下的Program.cs，调整配置和中间件顺序，确保Razor Pages路由优先级高于Swagger静态文件规则，参考正确配置如下：

var builder = WebApplication.CreateBuilder(args);

// 注册服务时显式给根Index页绑定根路由，避免被覆盖
builder.Services.AddRazorPages()
    .AddRazorPagesOptions(opts =>
    {
        opts.Conventions.AddPageRoute("/Index", "");
    });
builder.Services.AddSwaggerGen();

var app = builder.Build();

// 仅开发环境启用Swagger，避免生产环境路由冲突
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        // 显式指定Swagger UI前缀为/swagger，不占用根路径
        c.RoutePrefix = "swagger";
    });
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
// 移除所有手动注册的app.UseDefaultFiles()调用，避免默认文档优先级冲突
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();

// 必须将Razor Pages端点映射放在Swagger端点映射之前
app.MapRazorPages();

app.Run();

清理冲突文件
检查项目wwwroot目录下是否存在自动生成的index.html文件，若存在直接删除即可。
修正启动配置
打开Properties/launchSettings.json，将对应启动配置项的launchUrl值改为Index，避免启动时被默认文档规则错误重定向：
```
"launchUrl": "Index",
```
临时兼容方案（快速修复导航跳转）
若暂时不想调整全局配置，可直接修改_Layout.cshtml中的首页导航链接，绕开存在bug的标签助手路由生成，直接写死目标路径：
```
<li class="nav-item">
    <a class="nav-link text-white" href="/Index">Home</a>
</li>
```

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