ServiceStack虚拟目录与SPA路由冲突致API Explorer故障解决问询

问题根源 #

配置变更后，HandlerFactoryPath将ServiceStack API限定在/api路径，但API Explorer的静态资源（如ss-assets、swagger-ui）仍尝试从根目录加载导致404；同时重写规则未正确区分SPA路由与ServiceStack资源路径，引发功能故障和潜在冲突。

分步解决方案 #

1. 正确配置ServiceStack的HandlerFactoryPath

确保所有ServiceStack请求都路由到/api路径，彻底隔离SPA路由：

app.UseServiceStack(new AppHost {
    HandlerFactoryPath = "/api"
});

2. 调整.NET Core重写规则

重写规则需排除/api路径，处理SPA回退的同时修正API Explorer资源路径：

var rewriteOptions = new RewriteOptions()
    // 非/api路径且非文件请求，转发到SPA入口
    .AddRewrite(@"^(?!api)(.*)$", "index.html", skipRemainingRules: true)
    // 映射Swagger UI资源路径
    .Add(@"^api/swagger-ui/(.*)$", "/swagger-ui/$1")
    // 映射ServiceStack内置静态资源路径
    .Add(@"^api/ss-assets/(.*)$", "/ss-assets/$1");

app.UseRewriter(rewriteOptions);

3. 严格控制中间件顺序

中间件加载顺序决定请求处理优先级，必须按以下顺序配置：

// 先处理静态文件（SPA资源、ServiceStack静态资源）
app.UseStaticFiles();
// 应用重写规则
app.UseRewriter(rewriteOptions);
// 最后处理ServiceStack API请求
app.UseServiceStack(new AppHost { HandlerFactoryPath = "/api" });

4. 清理残留配置

彻底移除之前SharpPagesFeature和FallbackService的相关代码，避免冲突：

// 删除以下配置（如果存在）
// Plugins.Add(new SharpPagesFeature());
// app.UseFallbackService<FallbackService>();

5. 验证API Explorer访问

配置完成后，通过/api/ui访问API Explorer，确认页面正常加载且无控制台报错。ServiceStack会自动将元数据页面映射到HandlerFactoryPath下的/ui路径。

验证效果 #

• SPA自定义路由（如/modules）正常响应
• API Explorer（/api/ui）加载无异常
• ServiceStack请求完全通过/api路径发起，与SPA资源彻底隔离，消除未来冲突风险

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