必须完成安装、迁移、权限控制和环境适配四步闭环操作，否则/telescope路径404或数据不采集；生产环境默认禁用且不可逆开启。
要在 Laravel 项目中快速启用 Telescope 调试面板，必须完成安装、迁移、权限控制和环境适配四步闭环操作，漏掉任一环节都会导致 /telescope 路径 404 或数据不采集，尤其注意生产环境默认禁用且不可逆开启。
安装与初始化
在项目根目录执行：composer require laravel/telescope --dev
运行 php artisan telescope:install → 此命令会发布配置文件 config/telescope.php 并生成数据库迁移文件；若此前已存在旧版迁移，该命令可能静默跳过，需手动确认 database/migrations/*_create_telescope_entries_table.php 是否生成。
执行 php artisan migrate → Telescope 默认依赖主应用数据库连接，【若 DB_CONNECTION 指向只读从库，此步必失败】；SQLite 用户请先检查 database/database.sqlite 文件是否可写（chmod 664 database/database.sqlite）。
启用访问与权限控制
Telescope 默认仅对 APP_ENV=local 环境开放，且要求请求来自本地 IP。打开 app/Providers/TelescopeServiceProvider.php，找到 gate() 方法：
方法一：允许当前登录用户访问（需已启用 Laravel Sanctum 或 Fortify）return $request->user() ? $request->user()->hasRole('admin') : false;
方法二：限制为开发机固定 IP（如公司内网出口 IP 是 192.168.10.5）return $request->ip() === '192.168.10.5';
【切勿删除 gate() 方法或直接 return true；否则任何人均可通过 /telescope 窥探敏感请求参数】
配置监控项与数据采集粒度
打开 config/telescope.php，重点调整以下三处：
第一步：扩大请求体记录上限 → 找到 'watchers' => [...] 中的 RequestWatcher::class 配置项，将 'size_limit' => 64 改为 512，否则上传文件或长 JSON 请求体被截断。
第二步：启用 SQL 绑定参数 → 在同一 RequestWatcher 配置中，确保 'with_bindings' => true，否则查 N+1 时看不到实际传入的 ID 值。
第三步：关闭非必要监听器 → 若只关注异常与查询，注释掉 MailWatcher::class 和 NotificationWatcher::class，避免测试邮件触发大量冗余记录。
启动服务并验证面板
执行 php artisan serve 启动本地服务。
浏览器访问 http://localhost:8000/telescope → 页面加载成功即表示基础链路通达。
触发一次接口请求（如 GET /api/users），刷新 Telescope 首页 → 出现带时间戳的请求条目，点击进入后能看到「SQL」标签页下完整查询语句及绑定值，说明采集与存储正常。
