Log::listen()是最轻量的异常捕获入口,因它在日志写入前最早获取原始上下文,不干扰错误响应流程,且需在app/common.php顶部早期注册,回调中不可throw异常、须区分CLI/HTTP环境取请求信息,并确保告警邮件包含IP、时间、URI、UA、堆栈等完整上下文。

为什么 Log::listen() 是最轻量的异常捕获入口
ThinkPHP 的日志系统在抛出异常后仍会记录完整错误栈,Log::listen() 能在日志写入前拿到原始上下文,比中间件或异常处理器更早介入,且不干扰原有错误响应流程。
常见错误现象:用 App::bind() 或全局异常类重写 render() 方法后,邮件发了但接口返回 500 页面卡死;或者日志里有错误,但钩子根本没触发——大概率是没在 app/common.php 或服务提供者中正确注册监听器。
- 必须在应用初始化早期注册,推荐放在
app/common.php最顶部(早于路由加载) - 监听回调函数里不要 throw 新异常,否则会中断日志写入,导致后续日志丢失
-
$level参数为'error'或'critical'才该发邮件,避免调试时刷爆邮箱
如何用 think-mail 发送带堆栈的告警邮件
直接调 Mail::send() 容易因 SMTP 配置失败导致主流程阻塞,必须加超时和降级逻辑;而且原始异常对象不能直接序列化进邮件正文,得用 $e->getTraceAsString() 提取可读堆栈。
使用场景:线上环境需快速定位 500 错误源头,但又不想每处 try/catch 都写一遍发信逻辑。
- SMTP 连接超时设为
5秒,失败时仅记录一条「邮件发送失败」日志,不抛异常 - 邮件主题固定为
[TP-ALERT] {$level} {$e->getMessage()},便于邮件客户端过滤 - 正文中必须包含
$_SERVER['REQUEST_URI']和$_SERVER['HTTP_USER_AGENT'],否则无法还原请求上下文
Log::listen(function (string $level, string $message, array $context) {
if (!in_array($level, ['error', 'critical'])) return;
$e = $context['exception'] ?? null;
if (!$e instanceof \Exception) return;
$mailData = [
'uri' => $_SERVER['REQUEST_URI'] ?? 'unknown',
'ua' => $_SERVER['HTTP_USER_AGENT'] ?? 'unknown',
'trace' => $e->getTraceAsString(),
'msg' => $e->getMessage()
];
// 此处调用 think-mail 发送,带 try-catch 和超时控制
});
Log::listen() 在 CLI 和 HTTP 下行为差异
CLI 模式下(如队列任务、定时脚本)没有 $_SERVER 全局变量,REQUEST_URI 会报 Notice;HTTP 模式下则可能因 FastCGI 缓存导致 $_SERVER 缺失部分字段。不区分环境直接取值,邮件内容就残缺。
性能影响:每次日志写入都执行一次钩子回调,若内部含数据库查询或远程 HTTP 请求,会拖慢所有日志操作——告警逻辑必须纯内存计算 + 异步发送(比如写到 Redis 队列再由独立进程消费)。
- CLI 下改用
$_SERVER['argv'][0]获取当前执行脚本名 - HTTP 下优先读
request()->url(), fallback 到$_SERVER['REQUEST_URI'] - 禁止在钩子里调
Db::table()或Cache::get(),哪怕只是查配置
邮件模板里最容易漏掉的关键字段
只写错误消息和堆栈,收件人点开邮件后还得手动翻日志查 IP、时间、请求参数——这违背“告警即上下文完整”的原则。很多团队上线后才发现,90% 的告警邮件没人点开看,因为信息太单薄。
兼容性影响:某些企业邮箱(如网易企业邮)会自动折叠长文本块,把堆栈藏成「展开更多」按钮;如果关键字段不在首屏前三行,运维第一眼就看不到。
- 必须前置显示
IP: {$_SERVER['REMOTE_ADDR'] ?? 'CLI'} - 必须包含
Time: {date('Y-m-d H:i:s')},服务器时间可能和日志文件时间不一致 - GET/POST 参数要 JSON 编码后截断到 500 字符以内,防止邮件体过大被拒收
事情说清了就结束。真正难的不是发邮件,是让每封邮件打开就能定位问题——字段少一个,排查时间就多五分钟。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!











