Laravel Debugbar Collectors 完全指南：20+ 数据采集器详解与配置实战

• 开发工具
• 后端

Laravel Debugbar 通过一组可插拔的 DataCollector（数据采集器）组件，把数据库查询、日志消息、视图渲染、路由信息、异常堆栈等运行时数据聚合到调试工具栏中。本指南以 docs/collectors.md 为核心脉络，结合 config/debugbar.php 与 src/CollectorProviders 源码实现，带你逐个掌握每个采集器的功能、配置参数与适用场景，学会按需裁剪采集器以避免性能损耗，并利用 Query EXPLAIN、查询软硬限制、Mail 预览等进阶能力提升日常调试效率。

采集器体系总览：默认启用与可选开关

Laravel Debugbar 的核心类 LaravelDebugbar 在boot()时通过registerCollectors()将每个采集器以「Provider 类 + 配置键」的形式注册：Provider 负责实例化对应的 Collector 并挂载事件监听器，配置键（如db、mail）决定是否注册。

从 LaravelDebugbar::registerCollectors() 可以看到完整的 Provider 映射，包括文档未展开的http_client（HTTP 客户端请求）、ai（laravel/ai agent 运行）与inertia（Inertia 集成）等新采集器。

默认启用的采集器

以下采集器在默认配置下即处于开启状态，无需任何设置：

注意：phpinfo在文档中列于默认启用组，而 config/debugbar.php 中其默认值已被改为env('DEBUGBAR_COLLECTORS_PHPINFO', false)，即发布新版配置后默认关闭，可通过环境变量重新开启；session、route同理（默认值分别为 false）。以你本地发布的配置文件为准。

需要在配置中开启的采集器

以下采集器默认关闭，需将对应配置键设为true才能启用：

开关机制与 Provider 注册

所有采集器的开关判定由 shouldCollect() 完成：读取debugbar.collectors.<name>，为false时直接跳过对应 Provider 的注册，从而不挂载任何监听器，这是控制开销的第一道闸门。

// config/debugbar.php 中 'collectors' 数组示例 'collectors' => [ 'phpinfo' => true, // Php version 'messages' => true, // Messages 'time' => true, // Time Datalogger 'memory' => true, // Memory usage 'exceptions' => true, // Exception displayer 'log' => true, // Logs from Monolog (merged in messages if enabled) 'db' => true, // Show database (PDO) queries and bindings 'views' => true, // Views with their data 'route' => true, // Current route information 'auth' => false, // Display Laravel authentication status 'gate' => false, // Display Laravel Gate checks 'session' => true, // Display session data 'symfony_request' => true, // Only one can be enabled.. 'mail' => false, // Catch mail messages 'laravel' => false, // Laravel version and environment 'events' => false, // All events fired 'default_request' => false, // Regular or special Symfony request logger 'logs' => false, // Add the latest log messages 'files' => false, // Show the included files 'config' => false, // Display config settings 'cache' => false, // Display cache events 'models' => false, // Display models 'livewire' => true, // Display Livewire (when available) 'jobs' => false, // Display dispatched jobs 'pennant' => false, // Display Pennant feature flags ],

⚠️性能警告：Debugbar 需要收集并渲染数据，会拖慢应用。当应用变慢时，优先尝试禁用部分采集器（尤其events、config、views.data这类高开销选项）。

Database Queries：数据库查询采集器

Query Collector 是 Debugbar 中最常用、功能最丰富的采集器，提供以下能力：

• 展示执行的查询及耗时（含参数绑定）
• 显示/标记重复查询
• 展示使用的参数
• 按需执行EXPLAIN查询并跳转 Visual Explain（默认关闭）
• 一键复制查询语句到剪贴板
• 显示查询来源并在编辑器中打开
• 用底部边框可视化查询耗时长短
• 将查询加入 Timeline（默认关闭）
• 通过软/硬限制避免查询过多拖慢 Debugbar
• 排除指定路径（如 session 或 vendor 目录）
• 显示查询内存占用（默认关闭）

对应配置如下（config/debugbar.php中options.db）：

'options' => [ 'db' => [ 'with_params' => true, // 渲染 SQL 时替换参数 'exclude_paths' => [ // 完全排除的路径 // 'vendor/laravel/framework/src/Illuminate/Session', // 排除 session 查询 ], 'backtrace' => true, // 使用回溯查找查询在你的文件中的出处 'backtrace_exclude_paths' => [], // 从回溯中排除的路径（默认之外） 'timeline' => false, // 把查询加入时间线 'duration_background' => true, // 根据执行耗时给每条查询显示底纹背景 'explain' => [ // 显示 EXPLAIN 输出 'enabled' => false, ], 'hints' => false, // 显示常见错误的提示 'show_copy' => true, // 显示查询旁边的复制按钮 'slow_threshold' => false, // 只跟踪超过该毫秒数的查询 'memory_usage' => false, // 显示查询内存占用 'soft_limit' => 100, // 超过软限制后不再捕获参数/回溯 'hard_limit' => 500, // 超过硬限制后忽略查询 ], ],

从 DatabaseCollectorProvider 源码可见各选项的真实作用：

• timeline为 true 时，会把 TimeDataCollector 注入 QueryCollector，使每条查询出现在 Timeline 面板；
• setLimits()接收soft_limit/hard_limit；
• backtrace开启后调用setFindSource()，结合路由器中间件列表追踪查询调用来源；
• explain与show_query_result还需满足 isStorageOpen()（存储 Open Handler 可用），因为按需 EXPLAIN 需要重新连接数据库执行；
• 事件监听通过QueryExecuted事件捕获查询，并支持slow_threshold阈值过滤（DatabaseCollectorProvider）。

该 Provider 还挂载了事务监听：TransactionBeginning/TransactionCommitted/TransactionRolledBack事件会被记录为「Begin Transaction / Commit Transaction / Rollback Transaction」条目，ConnectionEstablished事件则记录「Connection Established」；当memory_usage开启时，会在连接beforeExecuting钩子中启动内存统计（DatabaseCollectorProvider）。数据库查询异常（QueryException）与视图异常包装的查询异常也会被捕获进 Failed Queries（DatabaseCollectorProvider）。

On-demand query EXPLAIN：按需 EXPLAIN

开启options.db.explain.enabled后，Debugbar 中任何 SELECT 查询都可以按需执行 EXPLAIN（v3.14.0+，实验特性）。结果直接在界面中更新，还可跳转到 mysqlexplain.com 查看可视化执行计划。

按需 EXPLAIN 依赖 Open Handler 从存储中重新加载数据并回连数据库执行（源码依据：DatabaseCollectorProvider 中isStorageOpen($request)判断），因此需要启用存储且不要在生产公开环境开启storage.open。

Query limits：查询软硬限制

Query Hard & Soft Limits（v3.10.0+）用于限制默认显示的查询量：

• 软限制（soft_limit，默认 100）：达到后不再捕获参数绑定与回溯信息，只保留查询本身；
• 硬限制（hard_limit，默认 500）：达到后完全忽略后续查询，防止加载过多数据导致 Debugbar 卡顿；
• 若想完全不受限制，把对应选项设为null即可（源码：setLimits() 接受可空整型）。

Messages：调试消息采集器

Messages 采集器聚合所有debug()调用写入的内容以及写入日志的消息（源码：MessagesCollectorProvider 直接复用 LaravelDebugbar 中构造的 MessagesCollector）。debug()支持传入多个参数，甚至可以是复杂对象：

debug($user, $order, ['status' => 'pending']);

Trace：消息溯源

调用debug()时，会显示调用来源文件，并可通过配置的编辑器直接打开（v3.10.0+，options.messages.trace）。消息的 backtrace 排除路径可通过backtrace_exclude_paths追加（MessagesCollectorProvider）。

Messages 采集器另有三个实用选项（见 config/debugbar.php）：

• capture_dumps：捕获 Laravel 的dump();输出为消息；
• timeline（默认 true）：把消息加入时间线；
• backtrace_exclude_paths：追加排除路径。

Logger：日志消息采集器

当 Messages 采集器启用时，Log 消息（Monolog 写入）会合并进 Messages 标签页；否则会出现独立的 Monolog 标签页仅显示日志消息。

从 LogCollectorProvider 的注册逻辑看，其职责就是在 Laravel 的 Logger 与 Messages 采集器之间建立桥接。此外LaravelDebugbar还支持$debugbar->info(...)、$debugbar->error(...)等魔法方法直接写入消息采集器（见 LaravelDebugbar 的 @method 注解）。

Views：视图采集器

ViewCollector 展示当前加载的视图，功能包括：

• 显示使用的模板及其源码
• 可选加入时间线
• 分组相似视图（对组件场景很有用）
• 排除文件夹（如 Filament 或其它 vendor 组件）
• 可选展示视图数据（可能较重）

'options' => [ 'views' => [ 'timeline' => false, // 把视图加入时间线（实验性） 'data' => false, // true 显示全部数据，'keys' 只显示键名，false 不显示参数 'group' => 50, // 分组重复视图。传数值自动分组，或传 true/false 强制开关 'exclude_paths' => [ // 不希望出现在视图列表中的路径 'vendor/filament' // 默认排除 Filament 组件 ], ], ],

实现上，ViewsCollectorProvider 监听composing:*事件，在每次视图被组合渲染时调用$viewCollector->addView()记录视图实例。

Timeline：时间线采集器

Timeline 展示从应用启动（LARAVEL_START）到响应的 Booting 与应用计时。默认包含「Booting」与「Application」两个阶段（源码：booted()）。

'options' => [ 'time' => [ 'memory_usage' => false, // 用内存起始值减去结束值计算，可能不精确 ], ],

Route：路由采集器

显示当前路由及其中间件列表。

'options' => [ 'route' => [ 'label' => true, // 在工具栏上显示完整路由 ], ],

Exceptions：异常采集器

显示应用产生的所有错误（含堆栈跟踪）。除自动捕获外，也可以手动添加异常：

debugbar()->addThrowable($throwable);

该能力由 AbstractCollectorProvider::addThrowable() 实现：当 exceptions 采集器存在时，把 Throwable 追加到ExceptionsCollector。此外，若开启error_handler，PHP 级别的弃用警告（deprecation）等也会被捕获并转入异常/消息面板（LaravelDebugbar::handleError()），error_level可控制捕获的错误级别。

Session：会话采集器

显示当前会话数据。

会话密钥可以通过options.session.masked列表脱敏隐藏（见 config/debugbar.php）。

Request：请求采集器

显示请求信息，如 headers、数据、Cookie 等。敏感数据默认隐藏，可自定义要隐藏的敏感键：

'options' => [ 'symfony_request' => [ 'hiddens' => [], // 用数组路径隐藏敏感值，例如 request_request.password ], ],

Livewire：Livewire 组件采集器

仅当页面使用 Livewire 时激活，显示页面上渲染的 Livewire 组件（v3.3.3+）。

PHP Info：PHP 版本采集器

一个显示当前 PHP 版本的小组件。

Gate：Gate 授权采集器

显示 Gate 检查是通过还是失败（v2.1.0+，默认关闭）。实现上监听GateEvaluated事件，每次授权评估都调用addCheck($event->user, $event->ability, $event->result, $event->arguments)（源码：GateCollectorProvider）。

可选配置（见 config/debugbar.php）：

'options' => [ 'gate' => [ 'trace' => false, // 追踪 Gate 检查的来源 'timeline' => false, // 把 Gate 检查加入时间线 ], ],

trace开启后会为每条 Gate 检查记录文件来源与回溯排除路径（GateCollectorProvider）。

Events：事件采集器

与 Timeline 类似，但会加入所有事件。注意这会收集大量数据，请谨慎使用。

'options' => [ 'events' => [ 'data' => false, // 收集事件数据、监听器 ], ],

配置文件还提供了更细的选项（config/debugbar.php）：

'options' => [ 'events' => [ 'data' => env('DEBUGBAR_OPTIONS_EVENTS_DATA', false), // 收集事件数据 'listeners' => env('DEBUGBAR_OPTIONS_EVENTS_LISTENERS', false), // 把监听器加入事件数据 'excluded' => [], // 例如 ['eloquent.*', 'composing', Illuminate\Cache\Events\CacheHit::class] ], ],

excluded可用通配符或类名排除高频事件，是控制数据量的关键手段。

Auth：认证状态采集器

一个显示当前登录状态的组件，外加一个包含更多信息的采集器（v1.2.2+，默认关闭）。实现基于 MultiAuthCollector，读取config('auth.guards')遍历所有 guard（源码：AuthCollectorProvider）。

'options' => [ 'auth' => [ 'show_name' => true, // 在 debugbar 中显示用户名/邮箱 'show_guards' => true, // 显示使用的 guards ], ],

Mail：邮件采集器

显示发送的邮件（默认关闭）。

Mail Preview：邮件预览

当邮件附带正文时，点击「View Mail」即可打开邮件的渲染预览（v3.12.0+，options.mail.show_body默认 true）。

Mail 采集器还支持把邮件加入时间线（options.mail.timeline，默认 true），完整配置见 config/debugbar.php。

Laravel Info：Laravel 信息采集器

显示当前 Laravel 版本、环境（environment）与 locale（默认关闭）。

Memory Usage：内存使用采集器

显示应用的内存使用情况（默认关闭）。

'options' => [ 'memory' => [ 'reset_peak' => false, // 采集前运行 memory_reset_peak_usage 'with_baseline' => false, // 把启动时内存作为峰值基线 'precision' => 0, // 内存取整精度 ], ],

Config：配置采集器

显示加载的配置值（v3.0+，默认关闭）。

⚠️安全警告：开启此采集器可能暴露敏感凭据（如数据库密码、APP_KEY 等）。务必确保你的应用不对外公开！

敏感配置键可通过options.config.masked数组隐藏（config/debugbar.php）。

Cache：缓存采集器

以时间线形式展示缓存命中/未命中（v3.0.0+，默认关闭）。

'options' => [ 'cache' => [ 'values' => true, // 收集缓存值 ], ],

另有options.cache.timeline（默认 false）可把缓存事件加入主时间线（config/debugbar.php）。

Models：模型采集器

显示每个 Eloquent 模型被加载的次数（v3.2.5+，默认关闭）。如果某模型加载次数过高，说明应考虑把部分逻辑移到 SQL 中，而不是在 PHP 中处理大型 Collection。

Jobs：队列任务采集器

显示本次请求派发的队列任务（v3.2.5+，默认关闭）。

Logs：日志文件采集器

显示 storage/logs 下日志文件的最新内容（默认关闭）。可通过options.logs.file指定额外文件：

'options' => [ 'logs' => [ 'file' => null, // 附加文件 ], ],

源码中默认回退到laravel.log（LogsCollectorProvider），file为相对 storage/logs 的路径。

Pennant：特性开关采集器

显示本次请求中检查过的所有 Pennant feature flags（v3.14.0+，默认关闭）。

Files：文件采集器（已废弃）

显示 PHP 引入/包含的所有文件（默认关闭）。

⚠️已废弃：该采集器主要在 OPcache 普及之前用于优化文件加载，现已不再推荐使用。

自定义采集器与进阶玩法

除内置采集器外，config/debugbar.php 提供了custom_collectors注册通道，可以添加自定义 DataCollector 或可调用类：

'custom_collectors' => [ // MyCollector::class => env('DEBUGBAR_COLLECTORS_MYCOLLECTOR', true), ],

注册逻辑见 registerCustomCollectorProviders()：若类实现DataCollectorInterface则直接addCollector()，否则作为 invokable 类调用（此时可通过容器注入依赖）。

另外，collectors.md 之外，仓库还提供了多项开箱即用的集成采集器：

• HTTP Client（http_client，默认开启）：显示 HTTP 客户端发起的请求，支持masked脱敏与timeline（config/debugbar.php）；
• AI 采集器（ai，默认开启）：显示 laravel/ai agent 运行记录，values控制是否收集 prompt/response/tool 正文（config/debugbar.php）；
• Inertia 采集器（inertia，默认开启）：显示 Inertia 页面数据，pages选项指向 Inertia 视图目录（默认js/Pages，config/debugbar.php）。

调优建议：让 Debugbar 更快

综合 collectors.md 的警告与各采集器实现，给出以下实践建议：

1. 按环境裁剪采集器：生产环境不应开启 Debugbar；开发环境下若响应变慢，优先关闭events（数据量大）、config（扫描全部配置）、views.data（收集视图数据）等高开销项。
2. 利用查询限制：保持soft_limit/hard_limit默认值或按需调低，避免大量查询撑爆工具栏。
3. 使用排除路径：通过db.exclude_paths、views.exclude_paths、events.excluded过滤 vendor/session 等无关数据。
4. 敏感数据脱敏：为symfony_request、session、config、http_client配置masked/hiddens，防止凭据泄露。
5. 按需启用重量级功能：EXPLAIN、查询结果回放、邮件预览等均依赖存储与 Open Handler，仅在需要时开启，且切勿在生产公开环境启用storage.open（config/debugbar.php 中有明确警告）。

掌握每个采集器的开关与选项后，你就能把 Laravel Debugbar 从「默认工具栏」升级为贴合自己项目的数据洞察面板，在定位慢查询、追踪事件风暴、审计授权逻辑时事半功倍。

• 开发工具
• 后端