启用 Clockwork 面板需同时满足：包已安装、中间件注册、浏览器插件或路由访问可用；缺一不可，且需 APP_DEBUG=true，响应头 X-Clockwork-Id 等未被覆盖或丢弃。
Clockwork 不是 Laravel 自带的调试工具，它需要单独安装和配置；直接 composer require 后不改配置，Clockwork::startRecording() 也不会自动显示面板。
怎么在 Laravel 项目中启用 Clockwork 面板
必须同时满足三个条件：包已安装、中间件注册、浏览器扩展或路由访问可用。缺一不可。
- 运行
composer require itsgoingd/clockwork（Laravel 10+ 推荐用 v5.3+） - 确认
app/Http/Kernel.php的$middlewareGroups['web']中已包含\Clockwork\Support\Laravel\ClockworkMiddleware::class（新版会自动注册，但需检查是否被注释或覆盖） - 开发环境必须开启
APP_DEBUG=true，否则 Clockwork 中间件会跳过记录 - 访问
/__clockwork/<id></id>可查原始数据，但推荐装官方浏览器插件（Chrome/Firefox 搜 “Clockwork”），插件会自动注入面板 UI
为什么开了插件也看不到面板？常见拦截点
最常被忽略的是响应头缺失或被覆盖，Clockwork 依赖 X-Clockwork-Id 和 X-Clockwork-Version 响应头通信。
- 中间件顺序错误：若自定义中间件调用了
$response->setContent()或返回了新 Response 实例，可能清空 Clockwork 注入的 headers - Nginx/Apache 配置中启用了
fastcgi_buffering off或代理时 strip 了自定义 header（尤其在 Docker 或反向代理后） - 使用了
dd()、exit或未完成的响应（如流式输出未 close），导致 Clockwork 的terminate()无法执行，headers 不写入 - 前端 JS 报错（比如混用了其他调试工具的全局变量）也会让面板加载失败，可打开浏览器控制台看是否有
Clockwork is not defined类错误
Clockwork::info() 和 Log::debug() 有什么区别
前者只在 Clockwork 面板中可见，不落盘；后者写入日志文件，且默认不带上下文快照。
立即学习“PHP免费学习笔记（深入）”；
-
Clockwork::info('user login', ['user_id' => $user->id, 'ip' => request()->ip()])会在面板的 “Timeline” 和 “Data” 标签页显示结构化数据 + 调用栈 -
Clockwork::startEvent('cache-fetch')/Clockwork::endEvent('cache-fetch')可手动标记耗时区间，比microtime(true)更直观 - 注意：
Clockwork::warn()和Clockwork::error()会同时触发面板高亮和 PHP error_log，但不会抛异常 - 不要在生产环境调用这些方法——即使
APP_DEBUG=false，它们仍会执行并产生轻微开销
如何排查 Clockwork 数据没更新或延迟显示
本质是数据没发到浏览器，或浏览器没收到通知，不是“面板坏了”。优先查网络和生命周期。
- 打开浏览器 Network 面板，过滤
__clockwork，看是否发出请求、状态是否 200、响应体是否为空 JSON - 检查 Laravel 日志里有没有
clockwork.*相关报错（例如 SQLite 文件不可写、Redis 连接失败） - 如果用了
CLOCKWORK_STORAGE=redis，确认REDIS_HOST和REDIS_PASSWORD正确，且 Redis 中有clockwork:*key - 在命令行运行
php artisan clockwork:clear清理缓存数据（仅 v5.2+ 支持）
真正麻烦的从来不是装不上，而是它悄悄工作又悄悄失败——比如中间件被覆盖、header 被吞、存储驱动连错实例。每次怀疑 Clockwork 失效，先抓一个真实请求的完整响应头和 __clockwork 请求响应体，比重装包有用得多。
