Laravel Telescope使用与应用监控教程

Laravel Telescope 是一款强大的本地开发调试工具，但其使用极易因环境配置、服务注册、监听器启用等细节疏漏而失效——从安装后页面404、数据采集为空、SQL参数被隐藏，到误入生产环境引发性能雪崩，几乎所有问题都源于对它“仅限 local + debug 模式全链路严格生效”这一核心设计逻辑的误解；本文直击五大高频踩坑场景，手把手厘清环境判断、路由注册、watcher 配置、参数显示与生产禁用的关键要点，帮你真正用好这个本该“开箱即查、所见即所得”的调试利器。

安装 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 可过滤噪音。

• 要监控队列任务，确保 '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)

Telescope 的数据采集链路很短，但每个环节都卡在具体配置和环境判断上。最容易被忽略的是：它不依赖「你有没有访问 /telescope 页面」，而完全取决于「当前请求生命周期中 watcher 是否被注册并触发」——所以哪怕页面能打开，也可能什么数据都没有。

理论要掌握，实操不能落！以上关于《Laravel Telescope使用与应用监控教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！