Telescope 默认仅在 APP_ENV=local 且 APP_DEBUG=true 时启用,需检查环境配置、运行 telescope:install 和 migrate、注册 TelescopeServiceProvider、开启对应 watcher 并配置 show=true 显示 SQL 参数,严禁在生产环境启用。

安装 Telescope 后页面 404 或路由不生效
Telescope 默认只在 local 环境启用,且要求 APP_ENV=local 和 APP_DEBUG=true 同时满足。如果改过环境配置、用了 Docker 或部署到测试服务器,很可能根本没加载 Telescope 的路由。
检查方式:运行 php artisan route:list | grep telescope,没输出就说明没注册成功。
- 确认
.env中APP_ENV=local(不能是dev或staging) - 执行
php artisan telescope:install后必须再跑php artisan migrate - 如果用的是 Laravel 11+,确认
config/app.php的providers数组里有App\Providers\TelescopeServiceProvider::class(Laravel 11 默认不自动发现) - 清缓存:
php artisan config:clear和php artisan view:clear
看不到队列/事件/日志等数据
Telescope 默认只监听部分类型(比如 HTTP 请求、异常),队列任务、事件广播、日志写入这些需要手动开启监听,否则数据压根不会采集。
核心配置在 config/telescope.php 的 watchers 数组里,每个 watcher 对应一类行为,enabled 控制开关,ignore 可过滤噪音。
立即学习“PHP免费学习笔记(深入)”;
- 要监控队列任务,确保
'Laravel\Telescope\Watchers\JobWatcher' => true,并确认队列驱动不是sync(同步模式下任务不走队列进程,Telescope 捕不到) - 想看
Log::info(),得打开'Laravel\Telescope\Watchers\LogWatcher' => true,但注意它默认只捕获error和critical级别,如需info需加'levels' => ['debug', 'info', 'notice', 'warning', 'error', 'critical'] - 事件监听依赖
EventWatcher,但如果用了->dispatchSync()或事件未真正触发(比如条件未满足),也不会出现在 Telescope 里
生产环境误开 Telescope 导致性能暴跌
Telescope 是调试工具,不是监控服务。它会记录每条请求的完整上下文(包括请求体、响应头、SQL 绑定参数),在高并发下直接拖垮数据库和内存。
它的设计逻辑是“开发阶段全量采集,上线后彻底关闭”,没有中间态。试图用 enabled 配置项做灰度或采样,实际效果极差。
- 绝对不要在生产环境的
.env里设APP_ENV=local—— 这是最常见的误操作 -
config/telescope.php中的'enabled' => env('TELESCOPE_ENABLED', true)不可靠,因为环境变量可能被覆盖,最稳妥的是在TelescopeServiceProvider的register()里硬编码判断:if ($this->app->environment('local')) { Telescope::start($this->app); } - 已上线项目若临时需要排查,优先用
php artisan tinker+DB::enableQueryLog()或日志文件,而不是开 Telescope
SQL 查询显示 ? 占位符但看不到真实参数
这是 Telescope 默认行为,出于安全考虑隐藏了绑定参数。但调试时没参数等于盲调,尤其遇到 WHERE status = ? 却不知道 ? 是 'pending' 还是 1,问题根本没法定位。
关键点在于 Laravel 的查询日志机制本身支持参数展开,但 Telescope 的 QueryWatcher 默认没启用该选项。
- 修改
config/telescope.php中'Laravel\Telescope\Watchers\QueryWatcher'的配置,加上'slow' => 0, 'show' => true('show' => true是关键) - 注意:开启后所有 SQL 日志都会带参数,包括
INSERT的敏感字段值,切勿在任何非本地环境启用 - 如果仍只显示
?,检查是否用了 PDO 的预处理模拟(PDO::ATTR_EMULATE_PREPARES => true),这种模式下 Laravel 拿不到真实参数,只能靠日志拼接,此时应关掉模拟:DB::connection()->getPdo()->setAttribute(PDO::ATTR_EMULATE_PREPARES, false)



















