资源描述
Tracy Debugger 是专为 ProcessWire CMS/CMF 设计的高性能 PHP 调试与开发增强工具，集成 Tracy PHP Debugging Library，提供实时变量检查、SQL 查询分析、路由追踪、异常可视化、AJAX 请求调试等深度诊断能力。适用于 ProcessWire 开发者在本地开发、性能调优及生产环境（安全模式下）快速定位逻辑错误与性能瓶颈，显著提升 PHP 开发效率与代码可靠性。
详细内容
## 工具定位与核心价值
Tracy Debugger 是 ProcessWire 生态中事实标准的调试增强工具，基于广受赞誉的 [Tracy PHP Debugging Library](https://tracy.netlify.app/) 深度定制，非通用型调试器，而是紧密耦合 ProcessWire 内核的「原生级」开发伴侣。其核心价值在于：将抽象的 PHP 运行时状态具象化、可交互、可追溯——不仅展示「哪里出错了」，更揭示「为什么错」和「如何优化」，大幅降低 ProcessWire 项目（尤其是模块开发、钩子调试、API 构建）的认知负荷与排查耗时。
## 主要功能列表
- **实时调试面板（Debug Bar）**：悬浮式响应式面板，显示请求生命周期关键指标（执行时间、内存占用、SQL 查询数/耗时、HTTP 头、会话/cookie 状态）
- **智能变量倾倒（Dump & Inspector）**：支持 `bd()`、`bdr()` 等快捷函数，高亮语法、可折叠结构、对象属性/方法实时预览，兼容 ProcessWire Page、Field、WireArray 等原生对象
- **SQL 查询分析器**：捕获并高亮所有数据库查询（含参数绑定），标记慢查询（>50ms）、重复查询及未索引 WHERE 条件，支持一键 EXPLAIN
- **路由与钩子调试**：可视化当前请求匹配的模板、路由规则；列出已注册钩子（Hook）、触发顺序及执行耗时，支持禁用特定钩子进行隔离测试
- **AJAX/REST API 调试**：自动捕获并格式化 AJAX 响应（JSON/XML）、请求头、原始 POST 数据，支持模拟不同 Content-Type 请求
- **安全生产模式**：通过配置启用「只对指定 IP/角色可见」的调试面板，满足上线环境合规性要求
- **扩展生态支持**：内置对 MarkupSEO、ProCache、Lingo 等主流 ProcessWire 模块的调试适配，自动注入模块特有诊断信息
## 典型使用场景
- 快速验证 Page 查询结果是否符合预期（如 `$pages->find('template=blog, limit=10')` 返回数量与字段值）
- 定位模板中因 `$page->children()` 链式调用引发的 N+1 查询问题，并优化为批量加载
- 调试自定义 Module 中的 `___execute` 或钩子方法，实时查看 `$event->arguments` 和 `$event->return`
- 分析 API 接口响应延迟原因：区分是数据库查询慢、外部 HTTP 请求阻塞，还是模板渲染开销过高
- 协作开发时，通过 `bd($user->roles)` 快速确认权限上下文，避免因角色继承逻辑导致的访问控制异常
## 上手步骤与操作要点
1. **安装**：通过 ProcessWire Admin > Modules > Site > Add New，输入 `TracyDebugger` 并 Install（推荐使用 Composer 安装：`composer require adrianbj/tracy-debugger`）
2. **启用**：安装后自动激活，首次访问前台页面即显示悬浮调试栏（后台默认隐藏，需在模块设置中勾选「Show in Admin」）
3. **基础调试**：在 PHP 代码中插入 `bd($variable)` 输出变量；使用 `bdump($array, 'label')` 添加语义化标签便于识别
4. **高级配置**：进入模块设置页（Setup > Tracy Debugger），配置「Debug Bar Position」、「Slow Query Threshold」、「Allowed IPs」等关键参数
5. **生产环境注意事项**：务必关闭 `Show in Production` 或严格限制 `Allowed IPs`，避免敏感信息泄露；可结合 `.env` 文件动态切换调试开关
6. **故障排除**：若调试栏不显示，检查是否启用了 `Output Formatting = false` 的模板，或确认 `debug` 模式已在 `config.php` 中设为 `true`（`$config->debug = true;`）