beego 的 404 等错误页需显式注册,否则使用暴露框架信息的默认页;推荐用 beego.errorcontroller() 注册全局错误控制器,方法名如 error404,自动设状态码;也可用 beego.errorhandler() 注册函数处理器,但无模板渲染能力;this.abort() 可主动触发错误页,未注册字符串将导致空白响应或 panic。

Beego 的 404 和其他错误页面必须显式注册,不注册就永远用默认模板,且默认页会暴露框架版本和内部路径。
beego.ErrorController() 注册全局错误控制器
这是最常用、也最推荐的方式。它让 Beego 在匹配不到路由或调用 this.Abort() 时,自动跳转到你指定的 Controller 中对应状态码的方法。
-
beego.ErrorController(&controllers.ErrController{})必须放在beego.Run()之前,否则无效 - Controller 中方法名必须以
Error开头 + 状态码(如Error404)或自定义字符串(如ErrorDb),大小写敏感 - 方法内可直接使用
c.Data传值、c.TplName指定模板,无需手动设置 HTTP 状态码 —— Beego 会自动设为对应值(如Error404→ 404) - 模板路径默认在
views/下,比如c.TplName = "404.tpl"对应views/404.tpl
beego.ErrorHandler() 注册函数式错误处理器
适合轻量逻辑或需要完全控制响应体(比如返回纯 JSON 或重定向)的场景,但无法使用 Beego 的模板渲染和上下文方法。
- 注册方式:
beego.ErrorHandler("404", page_not_found),其中page_not_found是签名形如func(http.ResponseWriter, *http.Request)的函数 - 该方式绕过 Beego 的 Controller 生命周期,
c.Ctx、c.Data、c.TplName全部不可用 - 必须手动调用
t.Execute(rw, data)渲染模板,且需提前用template.ParseFiles()加载模板文件 - 若模板路径不在
beego.BConfig.WebConfig.ViewsPath下,需传入绝对路径或确保相对路径正确
Abort() 主动触发错误页的注意事项
this.Abort() 不是抛异常,而是中断当前请求流程并跳转到对应错误处理逻辑 —— 它之后的代码不会执行,这点常被忽略。
- 参数可以是标准状态码字符串(
"404"、"500"),也可以是任意自定义字符串(如"dbError"),只要已通过ErrorHandler或ErrorController注册过 - 未注册的字符串(如
this.Abort("notfound")但没注册ErrorNotfound)会导致 Beego 返回空白响应或 panic(取决于版本) - 在中间件或
Prepare()中调用this.Abort()同样生效,但要注意顺序:如果前置中间件已写入响应头,再 Abort 可能导致 Header already written 错误
容易被忽略的兼容性与调试点
Beego 1.12+ 和 2.x 版本对错误处理逻辑基本一致,但模板路径解析、ViewsPath 默认值、以及 Abort() 的 panic 行为略有差异。
- 测试时务必用真实 HTTP 请求(如
curl -v http://localhost:8080/xxx)验证,而不是直接 new Controller 调用 —— 后者不触发路由匹配,Abort()会静默失败 - 自定义模板中不要依赖未传入的
c.Data字段,否则模板渲染报错;建议在 Controller 方法里做兜底赋值,例如c.Data["errMessage"] = c.Data["errMessage"].(string) - 若使用
AutoRouter,404 仍由全局错误控制器接管,但需确认路由未被意外匹配(比如/api/:id匹配了/api/导致进不到 404) - 生产环境记得关闭
beego.BConfig.RunMode == "dev",否则默认错误页可能覆盖你的自定义页











