laravel 队列在任务失败时调用 `failed()` 方法，但若方法签名强制要求 `exception` 类型参数而实际传入 `null`，将触发“argument 1 passed to ... must be an instance of exception, null given”致命错误。正确做法是显式声明 `\exception $e = null`。
在 Laravel 队列系统中，failed() 方法并非总能接收到异常实例——当任务因超时、进程被强制终止、队列 worker 意外退出或重试耗尽后手动标记为失败等场景下，框架可能传入 null 而非 Exception 对象。此时，若你按 Approach 1 写法 public function failed(Exception $e)（未加全局命名空间前缀且无默认值），PHP 类型声明会严格校验，导致 TypeError。
✅ 正确写法如下（推荐）：
public function failed(\Exception $e = null)
{
if ($e) {
\Log::error('Job failed with exception:', [
'message' => $e->getMessage(),
'trace' => $e->getTraceAsString(),
]);
} else {
\Log::warning('Job failed without exception (e.g., timeout or manual failure)');
}
// 可在此执行通知、清理、状态更新等逻辑
}⚠️ 关键要点说明：
- 必须使用全限定名 \Exception：Exception 是 PHP 内置类，位于全局命名空间。若未加反斜杠 \，PHP 会在当前命名空间 App\Jobs 下查找 App\Jobs\Exception，导致解析失败或类型不匹配；
- 必须提供默认值 = null：Laravel 底层（CallQueuedHandler.php 第 174 行）在某些失败路径中会直接调用 $job->failed(null)，因此参数需允许 null；
-
避免 Approach 2 和 3：
- failed($e)（无类型提示）虽可运行，但丧失类型安全与 IDE 支持，且不符合 Laravel 官方约定；
- failed()（无参数）则完全无法获取任何错误上下文，失去诊断价值。
? 补充建议：
- 若需区分失败原因，可结合 $this->job->getException()（Laravel 9+）或检查 $e 是否为 null；
- 在 handle() 中主动抛出明确异常（如 throw new RuntimeException('Invalid data')），有助于确保 failed() 接收有效 Exception 实例；
- 生产环境务必启用队列监控（如 Horizon）并配置失败任务重试策略与告警机制。
遵循此规范，即可彻底解决该 TypeError，让失败处理逻辑健壮、可维护且符合 Laravel 最佳实践。
