必须在注册任何路由前调用app.OnErrorCode(iris.StatusNotFound, handler),否则404函数不会触发;它属于路由匹配失败后的专用分支,需置于New之后、Get/Post等路由注册及Run之前,并显式设StatusCode和Content-Type。

必须在注册任何路由前调用 app.OnErrorCode(iris.StatusNotFound, handler),否则你的404函数根本不会被触发。
注册时机错就全白搭
很多人写了 handler 却收不到效果,问题出在注册顺序上。Iris 的错误处理器不是“兜底”,而是“路由匹配失败后才走的专用路由分支”。如果你先写了 app.Get("/user/{id}", ...) 这类泛匹配路由,再注册 404 处理器,那所有未命中路径都会被前面那个 {id} 吃掉(返回 404 状态但走默认文本),你的自定义函数压根不执行。
-
app.OnErrorCode必须放在app.Get、app.Post等所有常规路由注册之前 - 也必须放在
app.Run()或app.Listen()之前 - 推荐结构:New → OnErrorCode ×2 → 静态资源 → 常规路由 → Listen
渲染 HTML 模板最稳妥
比拼写纠错更可控,也避免空结果导致页面空白。模板路径要和 RegisterView 的配置对齐:
- 假设你用
app.RegisterView(iris.HTML("./views", ".html")),那就把模板放./views/errors/404.html - handler 里直接写
ctx.View("errors/404.html"),不用加扩展名 - 确保模板里没调用未定义的
{{.xxx}},否则View会 panic 并退回到默认 404
想推荐相似路径?记得判空降级
ctx.FindClosest(3) 确实能返回编辑距离最近的几个已注册路径,但它只比对路径字符串,不校验 HTTP 方法,也不保证存在。常见坑:
- 如果没注册任何路由,
ctx.FindClosest返回空切片,直接 range 会 panic - 推荐逻辑应包裹在
if len(closest) > 0 { ... }里,否则页面白屏 - 别在 404 页面里嵌入搜索框并提交到
/search却没配这个路由——又进一次 404
别忽略状态码和 Content-Type
浏览器和爬虫依赖状态码做判断。Iris 不会自动帮你设 404,必须显式声明:
- 开头加
ctx.StatusCode(iris.StatusNotFound),否则响应是 200 + 你的 HTML,SEO 和调试都乱套 - 如果用
ctx.HTML(...),它会自动设text/html;但若用ctx.Write(...),得手动ctx.ContentType("text/html") - 避免在 handler 里调用
ctx.Next()或其它中间件逻辑,404 处理器应是终端响应
真正容易被忽略的是:404 handler 里不能依赖任何业务中间件(比如 auth、session),因为这些中间件在路由匹配失败时根本没机会执行。所有上下文数据必须由 handler 自己构造或从 ctx.Request().URL 解析。


















