report() 方法里不能直接发钉钉，因为其同步执行会受网络延迟或异常（如数据库连接失败）影响，导致请求超时或雪崩；应改用队列异步推送，并配置重试、脱敏、环境过滤与关键词匹配等安全机制。
为什么 report() 方法里不能直接发钉钉？
因为 Laravel 的 report() 是同步执行的，如果网络不稳定或钉钉 Webhook 响应慢，会拖慢整个请求响应，甚至导致超时。更严重的是，某些异常（比如数据库连接失败）发生时，可能连 HTTP 客户端都初始化不了——这时候强行发钉钉反而让错误雪上加霜。
稳妥做法是把推送逻辑异步化：
- 用 Laravel 的队列系统（如
redis或database驱动）封装钉钉通知任务 - 在
App\Exceptions\Handler::report()中只触发队列任务，不等待结果 - 确保队列 worker 已启动（
php artisan queue:work），且能访问外网
如何写一个可重试的钉钉通知任务？
新建任务类：php artisan make:job NotifyDingTalk，重点处理三点：格式兼容、失败重试、敏感信息脱敏。
示例关键逻辑：
public function handle()
{
$payload = [
'msgtype' => 'text',
'text' => [
'content' => sprintf(
"[Laravel Error] %s\n%s\nFile: %s:%d",
$this->exception->getMessage(),
$this->exception->getTraceAsString(),
basename($this->exception->getFile()),
$this->exception->getLine()
)
]
];
// 脱敏：避免把 DB_PASSWORD、API_KEY 打进钉钉
$payload['text']['content'] = preg_replace(
'/(DB_PASSWORD|API_KEY|SECRET)\s*=\s*\S+/i',
'$1=***',
$payload['text']['content']
);
$response = Http::timeout(5)->post($this->webhookUrl, $payload);
if ($response->failed()) {
throw new Exception('DingTalk notify failed: ' . $response->body());
}
}
注意：
- 必须设置
tries = 3和backoff = 60，避免因临时网络抖动丢消息 - 不要在
handle()里用Log::error()再记录——队列失败日志本身就会落盘 - Webhook URL 必须存在环境变量中（
DD_WEBHOOK_URL），绝不可硬编码
在 Handler::report() 里怎么安全触发？
别直接 dispatch(new NotifyDingTalk(...))，要加兜底判断：
- 跳过开发环境（
app()->environment('local')）和测试异常（$exception instanceof \PHPUnit\Framework\AssertionFailedError） - 过滤低风险异常，比如
NotFoundHttpException或ValidationException，除非你真需要告警 404 - 对高频异常做简单限流：用
Cache::remember('dingtalk:rate:'.$exceptionClass, 60, fn() => 0)计数，1 分钟内超 5 次就跳过
典型调用片段：
public function report(Throwable $exception)
{
parent::report($exception);
if (app()->environment('production')
&& ! $exception instanceof \Illuminate\Http\Exceptions\NotFoundHttpException
&& ! $exception instanceof \Illuminate\Validation\ValidationException) {
NotifyDingTalk::dispatch($exception)->onQueue('notifications');
}
}
钉钉群机器人必须开启「自定义关键词」吗？
必须。否则消息根本不会推送到群聊——即使 HTTP 返回 200，钉钉服务端也会静默丢弃。
配置要点：
- 在钉钉群机器人管理页勾选「自定义关键词」，填入至少一个词，比如
[Laravel Error]（注意中括号也要写进去） - 关键词必须完整匹配，大小写敏感，且不能有空格（
LaravelError可以，Laravel Error不行） - 如果用 Markdown 类型推送，关键词得出现在
title或首段纯文本里，不能藏在代码块中
测试时最简单的验证方式：手动用 curl 发一条含关键词的消息，看是否进群。没进，99% 是关键词没配对或没开启开关。
另外，别忘了检查钉钉机器人的「安全设置」——IP 白名单如果开了，就得把你的服务器出口 IP 加进去，否则请求连握手都通不过。
