Telescope 装完无请求记录,需同时满足四条件:APP_ENV=local、TELESCOPE_ENABLED=true、TelescopeServiceProvider gate() 返回true、config/telescope.php中enabled配置生效;Ajax请求默认不显示在Requests页,需用telescope-toolbar或手动record;慢查询未标红因阈值过高或路径被ignore;prune默认保留异常,清异常需加--force。

Telescope 装完却看不到请求记录?检查中间件和启用状态
装完 php artisan telescope:install 和 php artisan migrate 后没数据,大概率是 Telescope 没真正跑起来。它默认只在本地环境(APP_ENV=local)且通过中间件授权后才记录数据。
- 确认
APP_ENV是local,不是production或staging - 检查
app/Providers/TelescopeServiceProvider.php中的gate()方法是否返回true—— 默认只允许request()->ip() === '127.0.0.1',如果你用 Docker、Valet 或远程开发,IP 不匹配就会静默丢弃所有记录 - 确保
TELESCOPE_ENABLED=true在.env里显式设置,否则即使环境正确也可能被关掉 -
config/telescope.php中的'enabled' => env('TELESCOPE_ENABLED', true)必须生效,别被其他配置覆盖
为什么 Ajax 请求不显示在 Requests 标签页?它根本不在那里
Telescope 的 Requests 标签页只展示完整 HTTP 请求-响应周期(即页面跳转或 API 入口),而前端发起的 fetch 或 XMLHttpRequest 默认不会出现在这里 —— 它们被归类为「后台请求」,需要额外工具才能捕获。
- 原生 Telescope 不监听 XHR/fetch,除非你手动触发
Telescope::recordRequest()或用中间件包裹这些路由 - 真正能自动抓取 Ajax 的是
laravel-telescope-toolbar(注意不是官方 Telescope),它通过浏览器端注入脚本+服务端钩子实现,安装后会在底部出现工具栏,Ajax 面板独立显示 - 如果你用 Livewire,它自带
X-Livewireheader,Telescope Toolbar 能识别并归类,但纯 API 路由如/api/posts仍需确认是否在only_paths配置中放开
慢查询没标红?检查 QueryWatcher 的 slow 阈值和 ignore_paths
数据库查询没高亮,并非没监控,而是条件没触发。Telescope 的 QueryWatcher 默认只把执行时间超过 100 毫秒的查询标记为「慢」,且会跳过某些路径。
Laravel Cloud(cloud.laravel.com)。此技能用于处理所有 Laravel Cloud 请求,包括搜索和读取数据。只要任务涉及 Laravel Cloud,即使用此技能。
- 修改
config/telescope.php中Watchers\QueryWatcher::class的'slow' => 50,调低阈值便于测试 - 确认
'ignore_paths' => ['nova-api*', 'horizon*']没误删你正在调试的路由前缀,比如你查的是/admin/users,但配置里写了'admin*'就全被跳过了 -
ignore_packages => true会过滤掉 Eloquent 内部调用(如Model::query()初始化),导致部分查询不出现,调试时建议设为false
prune 命令删不掉异常?因为 --keep-exceptions 默认开着
php artisan telescope:prune 默认保留异常记录,这是有意设计,不是 bug。如果你发现日志表体积大但异常没减少,很可能就是这个开关在起作用。
- 运行
php artisan telescope:prune --hours=48只清理 48 小时前的非异常数据,异常仍保留 - 要连异常一起清,必须显式加
--force:php artisan telescope:prune --hours=48 --force -
php artisan telescope:clear才是无差别清空全部,慎用,它绕过时间判断直接 truncate 表 - 生产环境建议用
--keep-exceptions+ 定时任务,既省空间又保关键错误线索
Telescope 的坑多数藏在配置层级叠加里:环境变量、配置文件、中间件 gate、watcher 自身开关,四层都得对上才真正生效。别只改一个地方就以为搞定了。










