Telescope 是请求生命周期快照记录器而非性能分析器；其常见问题包括环境配置错误、数据库权限不足、忽略 Request 标签页上下文、队列被 fake 或连接异常、dump 未启用 Watcher 或超限，且它只记录实际发生的行为。
Telescope 不是性能分析器，而是请求生命周期快照记录器——它不告诉你 CPU 占用率，但能让你 3 秒内确认「为什么这个 API 返回了 500」或「队列任务根本没 dispatch 出去」。
telescope:install 报错但没提示？先查环境和数据库权限
执行 php artisan telescope:install 静默失败，90% 是这两个原因：
-
APP_ENV不是local或testing（比如设成了staging），导致 Telescope 的enabled闭包默认返回false；临时解决：直接在config/telescope.php中把'enabled' => fn () => true - 数据库不可写：用 SQLite 时
database/database.sqlite没有写权限；用 MySQL/PostgreSQL 时DB_CONNECTION指向只读从库，迁移会卡住——运行php artisan migrate --pretend看是否报错
Exceptions 页面点进去没看到请求上下文？别跳过右侧 Request 标签页
Telescope 的 Exceptions 列表只显示异常类型和消息，真正关键的调试信息藏在每条异常右侧的 Request 标签页里：
- 它不是附属信息，而是触发该异常的完整 HTTP 请求快照：含原始
$_POST、$_GET、headers、sessionID、中间件执行顺序 - 如果你在日志里看到
TokenMismatchException，但没复现路径，就靠这个标签页看当时提交的_token值和 session 是否匹配 - 注意：如果请求体过大（如上传文件），默认会被截断；需在
config/telescope.php中调大'size_limit' => 64（单位 KB）
Jobs 页面显示空列表？先确认有没有 fake 队列或 dispatcher 被禁用
「队列任务没执行」不等于「任务失败」，更可能是根本没进队列：
- 检查
app/Providers/AppServiceProvider.php是否误加了Queue::fake()—— 这会让所有dispatch()调用静默丢弃，Telescope 里自然看不到任何条目 - 确认
QUEUE_CONNECTION配置正确，且对应连接（如redis）服务可连；用php artisan tinker执行dispatch(new \App\Jobs\ExampleJob)看是否报连接错误 - Jobs 页面顶部有 Dispatched 和 Failed 切换按钮——很多人只看 Failed，却忽略 Dispatched 为空才是真问题
想看 dump() 输出但 Telescope 里没记录？启用 DumpWatcher 并留意 size_limit
默认情况下 dump() 不会被捕获，必须显式启用：
- 在
config/telescope.php的'watchers'数组中确保Laravel\Telescope\Watchers\DumpWatcher::class的'enabled'为true -
dump($user, $items)会被合并成一个条目；但若其中任一变量序列化后超限（默认size_limit是 1KB），整条 dump 就不会入库——建议对大对象用Telescope::recordDump(['id' => $user->id])主动控制 - 注意：dump 条目只在当前请求生命周期内可见，刷新页面就消失；它不是日志，不能跨请求追溯
Telescope 最容易被忽略的细节，是它不记录「没发生的事」：没有请求就没有 Requests 条目，没 dispatch 就没有 Jobs 条目，没抛异常就不会出现在 Exceptions 里——排查时得先确认行为是否真的触发了，而不是只盯着面板找记录。
