Iris需配置通配路由/{path:path}于所有显式路由之后，使任意前端路径均返回index.html以支持SPA；若顺序错误或未排除/api等路径，将导致404或API失效。
Iris 框架本身不处理前端路由，它只负责后端通配路由返回 index.html —— 这是 SPA 正常工作的前提。配置错或漏掉关键点，前端路由就会 404 刷新失败。
为什么 Iris 需要通配路由而不是普通 GET 路由
SPA 前端（如 Vue Router、React Router）依赖 History API 控制地址栏，但浏览器每次手动输入路径或刷新时，仍会向服务端发起真实请求。如果 Iris 没有匹配该路径的路由规则，就返回 404；而用户期望的是：无论访问 /user/123 还是 /settings?tab=profile，后端都应返回 index.html，让前端路由接管。
常见错误现象：Cannot GET /user/123、刷新页面直接 404、F5 后跳回首页
- 不能用多个
app.Get("/user/:id", ...)去穷举所有前端路由 - 不能只配
app.Get("/", ...)，它不匹配子路径 - 必须在所有具体路由之后注册通配规则，否则会被前置路由拦截
正确配置 catch-all 路由的两种写法
Iris 提供了 app.FileServer 和 app.Handle 两种主流方式，区别在于是否托管静态资源：
- 若前端构建产物（
dist/）已放在本地，用app.FileServer+iris.Dir更简洁 - 若需在返回前加逻辑（如鉴权、埋点），用
app.Handle("GET", "/{path:path}", ...)
推荐写法（假设前端打包输出在 ./dist）：
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
app.Handle("GET", "/{path:path}", func(ctx iris.Context) {
// 可选：排除 API 请求，避免把 /api/users 也返回 index.html
if strings.HasPrefix(ctx.Request().URL.Path, "/api/") {
ctx.StatusCode(404)
return
}
ctx.ServeFile("./dist/index.html")
})
注意：/{path:path} 是 Iris 的通配语法，不是正则；path 是参数名，可任意取，但必须带 :path 后缀。
静态资源与 HTML 分离部署时的坑
很多团队把 index.html 和 JS/CSS 分开托管（比如 Nginx 托管静态文件，Iris 只做 API），这时 Iris 不该返回 index.html，而是交由反向代理处理。容易踩的坑：
- 误在 Iris 中重复配置静态文件服务，导致 CSS/JS 404（因为路径被通配规则劫持）
- 没关掉 Iris 的默认静态文件自动服务（
app.StaticWeb或app.StaticEmbedded），和通配规则冲突 - 前端构建时
publicPath配置为/，但实际部署在子路径（如/app/），导致资源加载 404
验证方法：直接 curl http://localhost:8080/nonexistent-path，响应体应为 index.html 内容，且状态码是 200，不是 301 或 404。
最易被忽略的一点：Iris 的通配路由必须放在所有显式路由定义之后，否则像 app.Get("/api/users", ...) 这类路由永远收不到请求 —— 因为 /{path:path} 已提前匹配并返回了 index.html。
