Iris的app.OnErrorCode必须在注册任何路由前调用,否则404/500处理器不生效;它仅响应显式设置的状态码,不自动捕获未匹配路由,分组级错误处理需靠中间件路径前缀判断实现。

app.OnErrorCode 必须在注册任何路由前调用
404 和 500 页面不生效,八成是因为 app.OnErrorCode 写在了 app.Get、app.Post 或 app.Party 之后。Iris 的错误处理器是全局兜底逻辑,不是中间件,它只在显式设置状态码后触发,且注册时机严格依赖顺序。
常见错误写法:
app := iris.New()
app.Get("/home", homeHandler)
app.OnErrorCode(iris.StatusNotFound, notFoundHandler) // ❌ 晚了!
正确顺序:
app := iris.New()
app.OnErrorCode(iris.StatusNotFound, notFoundHandler) // ✅ 第一或第二行
app.OnErrorCode(iris.StatusInternalServerError, err500Handler)
app.Get("/home", homeHandler)
app.Get("/user/{id:uint64}", userHandler)
-
app.OnErrorCode必须传框架常量(如iris.StatusNotFound),不能传字面量404或"404",否则类型不匹配,注册失败 - 如果你用了
app.StaticWeb("/static", "./public"),访问不存在的静态文件(如/static/missing.js)不会进OnErrorCode—— 这是http.FileServer自己返回的 404,和路由层无关 - 泛匹配路由(如
app.Get("/{path:path}", ...))会吞掉所有未命中路径,导致OnErrorCode完全失效;这类路由必须放在最后,且慎用
404 处理器不会自动捕获“未匹配路由”
Iris 的 OnErrorCode(iris.StatusNotFound, handler) 不是“未找到路由时自动调用”,而是“当 handler 显式调用 ctx.StatusCode(iris.StatusNotFound) 时才触发”。默认的未匹配行为由框架内置逻辑处理,不经过你的回调。
所以要真正启用自定义 404 页面,得主动制造一次 404 响应。最稳妥的做法是加一个兜底路由:
app.Get("/{path:path}", func(ctx iris.Context) {
ctx.StatusCode(iris.StatusNotFound)
})
- 这个兜底路由必须放在所有常规路由之后,否则会提前截断正常请求
- 不要在兜底路由里直接
ctx.View("404.html")—— 要先设状态码,再渲染,否则响应体是 200 状态下的 404 页面,语义错误 - 若你希望推荐相似路径,可用
ctx.FindClosest(3),但务必检查返回切片长度:if len(closest) == 0 { ctx.StatusCode(404); ctx.WriteString("Not found"); return },否则页面空白
500 错误需靠 recovery 中间件 + OnErrorCode 协同处理
panic 导致的 500 不会自动触发 OnErrorCode,因为 panic 发生在 handler 执行中,尚未走到状态码写入阶段。必须用 recovery 中间件捕获并显式设码:
app.Use(func(ctx iris.Context) {
defer func() {
if r := recover(); r != nil {
ctx.StatusCode(iris.StatusInternalServerError)
ctx.Values().Set("error", fmt.Sprintf("%v", r))
}
}()
ctx.Next()
})
然后配合 OnErrorCode 渲染:
app.OnErrorCode(iris.StatusInternalServerError, func(ctx iris.Context) {
ctx.View("errors/500.html")
})
- 仅注册
OnErrorCode不够,panic 会被 net/http 默认恢复并返回空响应;必须中间件里 recover 并设码 -
ctx.Values()是跨中间件传递数据的安全方式,比全局变量或闭包更可靠 - 开发时若启用了
iris.DevMode,模板语法错误等底层异常可能绕过自定义处理器,直接输出调试堆栈 —— 生产环境务必关掉
分组级错误页只能靠中间件路径判断实现
app.Party("/v1").OnErrorCode(...) 是无效的 —— Party 实例没有 OnErrorCode 方法,编译报错。Iris 不支持分组级错误处理器。
想让 /v1/xxx 出错时走 v1 专属模板,而 /admin/xxx 走另一套,只能手动拦截:
app.Use(func(ctx iris.Context) {
ctx.Next()
statusCode := ctx.GetStatusCode()
path := ctx.Path()
if statusCode == iris.StatusNotFound && strings.HasPrefix(path, "/v1/") {
ctx.View("v1/404.html")
ctx.StopExecution()
} else if statusCode == iris.StatusInternalServerError && strings.HasPrefix(path, "/admin/") {
ctx.View("admin/500.html")
ctx.StopExecution()
}
})
- 必须在
ctx.Next()之后读取状态码,因为 handler 才会真正设置它 -
ctx.FindClosest返回的是全量路由中最接近的路径,不区分分组前缀;若真要分组内推荐,得自己遍历app.Routes().GetRoutes()过滤再计算,开销大,不建议生产使用 - 注意:如果同时注册了
app.Get("/404", ...)这类显式路由,访问/404就不会进你的 404 处理器 —— 路由匹配优先于错误处理器
ctx.StatusCode(404);而真正的路由未匹配,默认行为是纯文本响应,且不可拦截 —— 必须靠兜底路由主动触发。


















