PHP项目Telescope调试工具

wen PHP项目 2026-07-24 2

PHP项目Telescope调试工具详解

Telescope 是 Laravel 生态系统中一个强大的调试和监控工具,主要用于开发阶段的调试和问题排查。

PHP项目Telescope调试工具

主要功能

请求监控
- 记录所有 HTTP 请求
- 查看请求参数、响应内容
- 跟踪请求执行时间
数据库查询
- 记录所有 SQL 查询
- 查看查询耗时
- 支持查询参数绑定
日志查看
- 集中管理应用日志
- 按级别筛选（debug、info、error 等）
- 实时日志查看
异常追踪
- 记录异常信息
- 堆栈跟踪
- 请求上下文
邮件监控
- 查看发送的邮件
- 预览邮件内容
- 调试邮件模板
队列任务
- 监控队列作业
- 查看执行状态
- 调试失败任务
事件和缓存
- 跟踪事件触发
- 缓存操作记录
- Redis 命令监控

安装配置

# 安装 Telescope
composer require laravel/telescope --dev
# 发布资源
php artisan telescope:install
# 运行迁移
php artisan migrate

基础使用示例

// 在控制器中使用
use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
class UserController extends Controller
{
    public function index()
    {
        // Telescope 会自动记录这个请求
        $users = User::where('active', true)
                     ->orderBy('created_at', 'desc')
                     ->get();
        // 手动添加标签
        app('telescope')->tag('users:list');
        return response()->json($users);
    }
    public function store(Request $request)
    {
        // 自定义记录
        telescope()->record('user_creation', [
            'email' => $request->email,
            'name' => $request->name
        ]);
        // 添加自定义标签
        telescope()->tag(['user_created', 'admin_action']);
        $user = User::create($request->validated());
        return response()->json($user, 201);
    }
}

高级用法

自定义监控

// 创建自定义门面
use Illuminate\Support\Facades\Facade;
class Telescope extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'telescope';
    }
}
// 在代码中使用
Telescope::record('custom_event', [
    'user_id' => auth()->id(),
    'action' => 'export_data',
    'records_count' => 100
]);

条件记录

// 只在特定条件下记录
if (app()->environment('local')) {
    telescope()->record('debug_info', [
        'memory_usage' => memory_get_usage(true),
        'execution_time' => microtime(true) - LARAVEL_START
    ]);
}

自定义标签和过滤

// 配置文件 config/telescope.php
return [
    'watchers' => [
        Watchers\RequestWatcher::class => [
            'enabled' => env('TELESCOPE_ENABLED', true),
            'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
        ],
        // 可以禁用某些 Watcher
        Watchers\DumpWatcher::class => false,
    ],
    // 标签过滤器
    'tag_filter' => [
        'App\\' => true,
        'auth' => true,
    ],
];

实际应用场景

场景1：调试 API 请求

// API 控制器
class ApiController extends Controller
{
    public function complexOperation(Request $request)
    {
        // Telescope 会自动记录所有数据库查询
        $result = DB::transaction(function () use ($request) {
            // 复杂业务逻辑
            $user = User::findOrFail($request->user_id);
            $order = Order::create([...]);
            // 查看生成的 SQL 和性能
            return compact('user', 'order');
        });
        return response()->json($result);
    }
}

场景2：邮件调试

// 查看邮件发送情况
Mail::to($user->email)->send(new OrderConfirmation($order));
// Telescope 会记录邮件内容，无需实际发送

安全配置

// 生产环境配置
'gate' => [
    'enabled' => true,
    'email' => ['admin@example.com'],  // 仅允许特定用户访问
    'ips' => ['127.0.0.1'],            // 仅允许本地 IP
],
// 或在 AppServiceProvider 中
use Laravel\Telescope\Telescope;
public function boot()
{
    Telescope::auth(function ($request) {
        return $request->user() && 
               $request->user()->isAdmin();
    });
}

性能优化建议

仅开发环境启用

# .env 文件
TELESCOPE_ENABLED=false  # 生产环境禁用

限制记录数量

// config/telescope.php
'storage' => [
    'count' => 1000,  // 保留最近1000条记录
],

清理旧数据

# 定期清理
php artisan telescope:prune --days=7

最佳实践

结合调试辅助函数

// 使用 dd() 和 dump()
dd($variable);  // Telescope 会捕获
dump($variable); // 在 Telescope 中查看

使用标签分类

// 按业务模块标记
telescope()->tag(['payment', 'failed_transaction']);
telescope()->tag(['auth', 'login_attempt']);

监控关键操作

// 记录重要操作
public function criticalOperation()
{
    telescope()->record('critical_action', [
        'timestamp' => now(),
        'user' => auth()->user()->email,
        'action' => 'delete_user',
        'target' => $userId
    ]);
}

Telescope 是 Laravel 开发的得力助手，合理使用可以显著提高开发和调试效率，记住在生产环境谨慎使用,避免性能影响和数据泄露风险。