beego中触发404和500错误页需显式调用this.abort("404")或this.abort("500"),或由未捕获panic自动触发;默认仅路由未匹配时自动abort("404")。

Beego 中如何触发 404 和 500 错误页面
Beego 默认不自动渲染自定义错误页,必须显式调用 Abort() 或让 panic 发生才能进入错误处理流程。直接返回 HTTP 状态码(如 ctx.ResponseWriter.WriteHeader(404))不会触发 Beego 的错误页机制。
常见触发方式:
- 路由未匹配时,Beego 自动调用
Abort("404")—— 这是唯一默认触发点 - 在 Controller 方法中手动调用
this.Abort("404")或this.Abort("500") - Controller 方法内发生未被捕获的 panic,Beego 会捕获并调用
Abort("500")
如何配置自定义错误模板路径
Beego 通过 error_404.tpl 和 error_500.tpl 两个固定文件名查找模板,且**必须放在 views 目录下根路径**,不支持子目录(如 views/errors/ 会失败)。
确保以下配置已启用(默认开启,但需确认):
beego.ErrorViews = map[int]string{
404: "error_404.tpl",
500: "error_500.tpl",
}
如果使用 beego.Run() 启动,该映射默认存在;若手动初始化 App,需显式设置。
注意:模板文件编码必须为 UTF-8(无 BOM),否则可能渲染空白或报错。
模板里能用哪些变量和函数
Beego 错误模板只传入一个 .Data 对象,其内部结构取决于触发方式:
-
Abort("404")→.Data["status"] == "404",.Data["reason"]是字符串 "404" - panic 触发的 500 →
.Data["error"]是error接口值(可调用.Error()),.Data["stack"]是字符串格式的堆栈(仅开发模式开启) - 所有情况都可通过
.Data["request_uri"]获取原始请求路径
模板中不能调用自定义函数,也不能访问 Controller 中的 this.Data。简单示例 error_404.tpl:
<h1>Oops! Page not found</h1>
<p>You requested: <code>{{.Data.request_uri}}</code></p>
为什么本地开发能看到堆栈,线上却只有空白页
这是 Beego 的安全策略:仅当 beego.RunMode == "dev" 时,500 模板中的 .Data["stack"] 才有内容;生产环境("prod")下该字段为空,且默认关闭 panic 捕获日志输出。
要在线上记录真实错误,必须额外配置:
- 设置
beego.LogLevel = beego.LevelDebug(或更高) - 确保
beego.LogOutputs包含文件输出(如["file"]),否则 panic 日志只打到 console 并丢失 - 避免在
error_500.tpl中直接输出{{.Data.stack}},否则生产环境会渲染空内容甚至破坏 HTML 结构
真正容易被忽略的是:即使你写了完美的 error_500.tpl,如果没配日志输出,线上崩溃就只剩 Nginx 的 502 或浏览器白屏,根本看不到任何线索。











