Laravel如何使用Telescope进行调试？（安装和使用教程）_网络技术

发布时间 - 2025-12-17 00:00:00 点击率：次

Telescope 是 Laravel 官方调试工具，支持请求、日志、SQL 等实时监控，安装只需 composer require 和 artisan 命令，本地环境默认启用，提供界面化筛选与手动记录功能。

Telescope 是 Laravel 官方推出的调试工具，专为开发环境设计，能实时捕获请求、日志、数据库查询、缓存、队列、异常等详细信息。安装简单，界面直观，不需要额外配置数据库（默认用文件存储），适合快速定位问题。

在 Laravel 项目根目录执行以下命令：

运行 composer require laravel/telescope --dev（仅开发环境需要）
执行 php artisan telescope:install（发布迁移和配置）
运行 php artisan migrate（若使用数据库存储；如跳过此步，默认会用 storage/telescope 目录存 JSON 文件）
启动服务：php artisan serve，然后访问 /telescope（例如 http://localhost:8000/telescope）

默认情况下，Telescope 只对本地环境（APP_ENV=local）开放。如需自定义访问权限，可编辑 app/Providers/TelescopeServiceProvider.php 中的 gate() 方法：

允许所有本地请求：保持默认的 return $request->isLocal();
限制为特定 IP 或用户：比如只让管理员访问，可改成 return $request->user()?->can('viewTelescope');，并配合 Gate 定义权限
注意：生产环境切勿开启 Telescope，它会显著影响性能且存在安全风险

打开 /telescope 后，你会看到时间线式的数据列表。常用操作包括：

点击某条请求，展开详情页——能看到完整的请求头、响应内容、中间件执行顺序、SQL 查询（含绑定参数和执行时间）、日志行、事件广播、缓存操作等
顶部搜索栏支持按 URI、方法（GET/POST）、状态码、标签（tag）、异常关键词过滤
右侧「Filters」可勾选类型（如只看 Queries 或 Exceptions），也可输入自定义标签（比如在代码中用 Telescope::tag(['api', 'payment']) 标记关键流程）
每条记录右上角有「Prune」按钮，可手动清理单条记录（不影响其他数据）

除了自动采集，你还可以手动记录变量、调试语句或自定义事件：

记录普通变量：Telescope::recordDump($user, $order);（会在 Dump 标签下显示）
记录自定义监控项：Telescope::recordMessage('Payment processed', 'info', ['order_id' => 123]);
给某段逻辑加标签，方便筛选：Telescope::tag(['checkout']);（放在该逻辑开始前）
临时关闭采集（比如避免日志爆炸）：Telescope::stopRecording();，之后调用 Telescope::startRecording(); 恢复

基本上就这些。Telescope 不复杂但容易忽略细节——比如忘记清空旧数据导致加载变慢，或者没关掉生产环境访问。日常开发中，它比 dd() 和日志更系统，也比 Xdebug 更轻量。