# 调试技巧

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [public/static/js/admin.js](file://public/static/js/admin.js)
- [public/static/js/frontend.js](file://public/static/js/frontend.js)
- [public/static/js/wind.js](file://public/static/js/wind.js)
- [public/static/js/ajaxForm.js](file://public/static/js/ajaxForm.js)
- [public/static/js/jquery.js](file://public/static/js/jquery.js)
- [public/static/js/xd.js](file://public/static/js/xd.js)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/swagger/controller/ApiAdminIndexController.php](file://public/plugins/swagger/controller/ApiAdminIndexController.php)
- [public/plugins/swagger/controller/IndexController.php](file://public/plugins/swagger/controller/IndexController.php)
- [public/plugins/swagger/service/OpenApi.php](file://public/plugins/swagger/service/OpenApi.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
- [public/plugins/swagger/view/swagger.html](file://public/plugins/swagger/view/swagger.html)
- [public/plugins/swagger/view/widget.html](file://public/plugins/swagger/view/widget.html)
- [public/plugins/swagger/view/public/scripts.html](file://public/plugins/swagger/view/public/scripts.html)
- [public/plugins/swagger/view/public/head.html](file://public/plugins/swagger/view/public/head.html)
- [public/plugins/system_info/SystemInfoPlugin.php](file://public/plugins/system_info/SystemInfoPlugin.php)
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/ApiIndexController.php](file://public/plugins/system_info/controller/ApiIndexController.php)
- [public/plugins/system_info/view/widget.html](file://public/plugins/system_info/view/widget.html)
- [public/plugins/tianditu/TiandituPlugin.php](file://public/plugins/tianditu/TiandituPlugin.php)
- [public/plugins/tianditu/config.php](file://public/plugins/tianditu/config.php)
- [vendor/topthink/think-trace/src/config.php](file://vendor/topthink/think-trace/src/config.php)
- [vendor/thinkcmf/cmf-install/src/install/config.php](file://vendor/thinkcmf/cmf-install/src/install/config.php)
- [vendor/thinkcmf/cmf-install/src/install/data/config.php](file://vendor/thinkcmf/cmf-install/src/install/data/config.php)
- [vendor/thinkcmf/cmf-captcha/src/config.php](file://vendor/thinkcmf/cmf-captcha/src/config.php)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
本指南面向 ThinkCMF 的开发者与运维人员，聚焦于调试实战：基于 ThinkPHP 的 trace 调试工具、日志记录与级别配置；Xdebug 调试器的配置与使用；数据库查询调试（SQL 日志、慢查询与优化）；前端调试（浏览器开发者工具、AJAX 请求与 JS 错误排查）；常见问题（权限、路由、模板渲染）的排查思路；以及性能分析（内存、执行时间、瓶颈定位）。文档结合仓库中的实际文件与配置，提供可操作的步骤与图示。

## 项目结构
- 入口与路由
  - Web 根目录指向 public，入口文件为 public/index.php，API 入口为 public/api.php，路由入口为 public/router.php。
- 应用与插件
  - 应用位于 app 与 api 目录；插件位于 public/plugins 下，如 Swagger、SystemInfo、Tianditu 等。
- 前端脚本
  - 后台与前台脚本集中在 public/static/js，包含 admin.js、frontend.js、wind.js、ajaxForm.js、xd.js 等。
- 调试相关依赖
  - 通过 composer.json 可见 require-dev 中包含 topthink/think-trace，表明官方提供 trace 调试工具支持。
- 配置来源
  - ThinkCMF 使用 data/config 作为 ThinkPHP 配置目录，配合 .env 环境变量；插件与安装包内也存在各自 config.php。

```mermaid
graph TB
A["Web 服务器<br/>站点根目录指向 public"] --> B["入口文件<br/>public/index.php"]
A --> C["API 入口<br/>public/api.php"]
A --> D["路由入口<br/>public/router.php"]
subgraph "应用层"
E["应用 app/"]
F["应用 api/"]
end
subgraph "插件层"
G["Swagger 插件<br/>public/plugins/swagger"]
H["系统信息插件<br/>public/plugins/system_info"]
I["天地图插件<br/>public/plugins/tianditu"]
end
subgraph "前端脚本"
J["admin.js / frontend.js / wind.js / ajaxForm.js / xd.js"]
end
B --> E
B --> F
B --> G
B --> H
B --> I
B --> J
```

**图表来源**
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)
- [public/router.php](file://public/router.php)
- [public/static/js/admin.js](file://public/static/js/admin.js)
- [public/static/js/frontend.js](file://public/static/js/frontend.js)
- [public/static/js/wind.js](file://public/static/js/wind.js)
- [public/static/js/ajaxForm.js](file://public/static/js/ajaxForm.js)
- [public/static/js/xd.js](file://public/static/js/xd.js)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/system_info/SystemInfoPlugin.php](file://public/plugins/system_info/SystemInfoPlugin.php)
- [public/plugins/tianditu/TiandituPlugin.php](file://public/plugins/tianditu/TiandituPlugin.php)

**章节来源**
- [README.md](file://README.md)
- [composer.json](file://composer.json)

## 核心组件
- Trace 调试工具
  - 通过 require-dev 引入 topthink/think-trace，可在开发环境中启用调试面板与请求追踪。
- 日志与级别
  - ThinkPHP 默认日志系统可通过配置文件启用与调整级别；结合插件与应用层日志输出进行问题定位。
- Xdebug
  - 通过 php.ini 或 docker/php/conf.d 配置 xdebug.remote_* 参数，实现断点、变量监控与调用栈跟踪。
- 数据库调试
  - 使用 ORM 日志或数据库层日志记录 SQL；结合慢查询日志与 EXPLAIN 分析。
- 前端调试
  - 利用浏览器开发者工具 Network/XHR、Console、Sources；结合 admin.js/xd.js 等脚本进行 AJAX 调试。
- 性能分析
  - 使用 Xdebug/Blackfire/内存快照等工具定位热点函数与内存泄漏；结合路由与模板渲染路径分析瓶颈。

**章节来源**
- [composer.json](file://composer.json)
- [vendor/topthink/think-trace/src/config.php](file://vendor/topthink/think-trace/src/config.php)

## 架构总览
下图展示从浏览器到后端控制器、再到插件与服务层的典型请求链路，并标注调试关注点（日志、SQL、模板渲染、AJAX）。

```mermaid
sequenceDiagram
participant U as "浏览器"
participant R as "路由入口<br/>public/router.php"
participant I as "入口文件<br/>public/index.php"
participant C as "控制器<br/>App/Api/... 或 插件控制器"
participant S as "服务层<br/>Service/..."
participant DB as "数据库"
U->>R : "HTTP 请求"
R->>I : "分发到入口"
I->>C : "匹配路由并实例化控制器"
C->>S : "调用业务服务"
S->>DB : "执行查询/写入"
DB-->>S : "返回结果"
S-->>C : "组装响应数据"
C-->>U : "JSON/AJAX 响应"
Note over I,DB : "开启日志与 SQL 记录便于调试"
```

**图表来源**
- [public/router.php](file://public/router.php)
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)

## 详细组件分析

### Trace 调试工具
- 工具来源
  - 依赖 topthink/think-trace 在 require-dev 中声明，随框架自动加载与注册。
- 启用方式
  - 在开发环境开启 trace 面板，查看请求耗时、SQL 列表、变量与调用栈。
- 配置位置
  - trace 配置由 think-trace 包提供，具体键位与默认值可参考其配置文件。

```mermaid
flowchart TD
Start(["进入入口"]) --> LoadTrace["加载 think-trace 服务"]
LoadTrace --> EnablePanel{"是否启用调试面板？"}
EnablePanel --> |是| Panel["显示 Trace 面板<br/>含请求耗时/SQL/变量/调用栈"]
EnablePanel --> |否| Normal["常规请求处理"]
Panel --> End(["结束"])
Normal --> End
```

**图表来源**
- [composer.json](file://composer.json)
- [vendor/topthink/think-trace/src/config.php](file://vendor/topthink/think-trace/src/config.php)

**章节来源**
- [composer.json](file://composer.json)
- [vendor/topthink/think-trace/src/config.php](file://vendor/topthink/think-trace/src/config.php)

### 日志记录与级别配置
- 配置目录
  - ThinkCMF 将 data/config 作为 ThinkPHP 配置目录，可在此放置日志相关配置文件。
- 建议做法
  - 开发环境：记录 info 或 debug 级别，便于捕获 SQL 与变量。
  - 生产环境：记录 warning 或 error，避免敏感信息泄露。
- 插件与安装包
  - 插件与安装包内存在各自的 config.php，可在其中设置日志级别或输出目标。

**章节来源**
- [composer.json](file://composer.json)
- [vendor/thinkcmf/cmf-install/src/install/config.php](file://vendor/thinkcmf/cmf-install/src/install/config.php)
- [vendor/thinkcmf/cmf-install/src/install/data/config.php](file://vendor/thinkcmf/cmf-install/src/install/data/config.php)
- [vendor/thinkcmf/cmf-captcha/src/config.php](file://vendor/thinkcmf/cmf-captcha/src/config.php)

### Xdebug 调试器
- 安装与启用
  - 在 php.ini 或 docker/php/conf.d 中启用 xdebug 并配置远程调试参数。
- 断点与变量监控
  - 在控制器、服务层或插件方法处设置断点，观察变量变化与调用栈。
- 调用栈跟踪
  - 结合浏览器 Network 面板与 Xdebug 的调用栈，定位慢点与异常抛出位置。
- 注意事项
  - 生产环境务必关闭，避免性能损耗与安全风险。

[本节为通用调试方法说明，不直接分析具体文件，故无“章节来源”]

### 数据库查询调试
- SQL 日志
  - 开启 ORM 日志或数据库层日志，记录完整 SQL 语句与绑定参数。
- 慢查询分析
  - 使用慢查询日志与 EXPLAIN 分析索引命中情况与扫描范围。
- 优化建议
  - 为高频查询字段建立合适索引；避免 SELECT *；拆分复杂查询；使用分页与缓存。
- 在 ThinkCMF 中的应用
  - 控制器与服务层的查询逻辑均可通过日志与 trace 面板进行观测。

[本节为通用调试方法说明，不直接分析具体文件，故无“章节来源”]

### 前端调试
- 浏览器开发者工具
  - Network 面板查看请求与响应；Console 查看错误与警告；Elements/Styles 检查页面结构与样式。
- AJAX 请求调试
  - 关注 admin.js/xd.js 等脚本封装的请求，检查请求头、参数与响应体；利用断点观察回调执行。
- JavaScript 错误排查
  - 打开 Sources 面板，启用断点与条件断点；结合 Console 输出定位问题。

```mermaid
sequenceDiagram
participant B as "浏览器"
participant JS as "前端脚本<br/>admin.js / xd.js"
participant API as "后端 API<br/>public/api.php"
B->>JS : "触发交互事件"
JS->>API : "发起 AJAX 请求"
API-->>JS : "返回 JSON 响应"
JS->>B : "更新页面内容"
Note over JS,B : "Network/Console/Sources 协同定位问题"
```

**图表来源**
- [public/static/js/admin.js](file://public/static/js/admin.js)
- [public/static/js/xd.js](file://public/static/js/xd.js)
- [public/api.php](file://public/api.php)

**章节来源**
- [public/static/js/admin.js](file://public/static/js/admin.js)
- [public/static/js/xd.js](file://public/static/js/xd.js)
- [public/api.php](file://public/api.php)

### Swagger 插件调试
- 功能概述
  - Swagger 插件提供 API 文档与调试界面，便于前后端联调。
- 调试要点
  - 在 Swagger 页面中直接发起请求，观察响应与错误；结合后端日志与 trace 面板核对请求路径与参数。
- 相关文件
  - 插件入口、控制器、服务与视图文件均位于 public/plugins/swagger 下。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant SW as "Swagger 插件界面"
participant AC as "Swagger 控制器"
participant OP as "OpenAPI 服务"
Dev->>SW : "打开 Swagger 页面"
Dev->>AC : "选择接口并点击 Try it out"
AC->>OP : "生成/读取 OpenAPI 规范"
OP-->>AC : "返回规范数据"
AC-->>Dev : "展示响应与示例"
```

**图表来源**
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/swagger/controller/ApiAdminIndexController.php](file://public/plugins/swagger/controller/ApiAdminIndexController.php)
- [public/plugins/swagger/controller/IndexController.php](file://public/plugins/swagger/controller/IndexController.php)
- [public/plugins/swagger/service/OpenApi.php](file://public/plugins/swagger/service/OpenApi.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
- [public/plugins/swagger/view/swagger.html](file://public/plugins/swagger/view/swagger.html)
- [public/plugins/swagger/view/widget.html](file://public/plugins/swagger/view/widget.html)
- [public/plugins/swagger/view/public/scripts.html](file://public/plugins/swagger/view/public/scripts.html)
- [public/plugins/swagger/view/public/head.html](file://public/plugins/swagger/view/public/head.html)

**章节来源**
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/swagger/controller/ApiAdminIndexController.php](file://public/plugins/swagger/controller/ApiAdminIndexController.php)
- [public/plugins/swagger/controller/IndexController.php](file://public/plugins/swagger/controller/IndexController.php)
- [public/plugins/swagger/service/OpenApi.php](file://public/plugins/swagger/service/OpenApi.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
- [public/plugins/swagger/view/swagger.html](file://public/plugins/swagger/view/swagger.html)
- [public/plugins/swagger/view/widget.html](file://public/plugins/swagger/view/widget.html)
- [public/plugins/swagger/view/public/scripts.html](file://public/plugins/swagger/view/public/scripts.html)
- [public/plugins/swagger/view/public/head.html](file://public/plugins/swagger/view/public/head.html)

### 系统信息与天地图插件
- 系统信息插件
  - 提供系统状态与环境信息，可用于排查权限、路径与配置问题。
- 天地图插件
  - 提供地图组件与配置项，调试时关注配置文件与视图挂载。

**章节来源**
- [public/plugins/system_info/SystemInfoPlugin.php](file://public/plugins/system_info/SystemInfoPlugin.php)
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/ApiIndexController.php](file://public/plugins/system_info/controller/ApiIndexController.php)
- [public/plugins/system_info/view/widget.html](file://public/plugins/system_info/view/widget.html)
- [public/plugins/tianditu/TiandituPlugin.php](file://public/plugins/tianditu/TiandituPlugin.php)
- [public/plugins/tianditu/config.php](file://public/plugins/tianditu/config.php)

## 依赖分析
- Composer 依赖
  - require-dev 中包含 topthink/think-trace，表明 trace 调试能力由框架扩展提供。
  - require 中包含多个 thinkcmf/* 包，构成应用、API、安装与根资源等模块。
- 依赖关系图

```mermaid
graph LR
CMF["ThinkCMF 根项目"] --> TP["topthink/framework"]
CMF --> TRACE["topthink/think-trace"]
CMF --> APP["thinkcmf/cmf-app"]
CMF --> API["thinkcmf/cmf-api"]
CMF --> INSTALL["thinkcmf/cmf-install"]
CMF --> ROOT["thinkcmf/cmf-root"]
CMF --> STORE["thinkcmf/cmf-appstore"]
```

**图表来源**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)

**章节来源**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)

## 性能考虑
- 内存使用分析
  - 使用 Xdebug Memory Profiler 或内置快照工具，定位内存峰值与泄漏点。
- 执行时间统计
  - trace 面板与日志记录可辅助统计各阶段耗时；结合浏览器 Network 面板观察前端渲染与资源加载。
- 瓶颈定位
  - 优先检查慢查询、模板渲染循环、重复 AJAX 请求与未缓存的数据读取。
- 最佳实践
  - 合理使用缓存（Redis/Memcached）、延迟加载与分页；避免 N+1 查询；减少不必要的模板变量计算。

[本节为通用性能指导，不直接分析具体文件，故无“章节来源”]

## 故障排查指南
- 权限问题
  - 检查 data/config 与 public/upload 等目录写权限；确认 .env 与插件配置文件权限。
- 路由问题
  - 使用 public/router.php 与 public/index.php 的分发逻辑，结合 trace 面板查看路由匹配与控制器实例化过程。
- 模板渲染问题
  - 检查主题与插件视图文件是否存在；利用 trace 面板查看模板变量与渲染路径。
- AJAX 请求问题
  - 使用浏览器 Network 面板与 admin.js/xd.js 脚本断点，核对请求头、参数与响应状态码。
- Swagger 调试
  - 在 Swagger 页面直接测试接口，结合后端日志与 trace 面板核对请求路径与参数。

**章节来源**
- [public/router.php](file://public/router.php)
- [public/index.php](file://public/index.php)
- [public/static/js/admin.js](file://public/static/js/admin.js)
- [public/static/js/xd.js](file://public/static/js/xd.js)
- [vendor/topthink/think-trace/src/config.php](file://vendor/topthink/think-trace/src/config.php)

## 结论
通过 trace 调试工具、日志与级别配置、Xdebug 断点与调用栈、数据库 SQL 日志与慢查询分析、浏览器开发者工具与 AJAX 调试，以及针对权限、路由、模板与 Swagger 的专项排查，可以系统性地定位 ThinkCMF 的各类问题。结合性能分析与最佳实践，持续优化系统稳定性与用户体验。

## 附录
- 环境与入口
  - 站点根目录为 public，入口文件为 public/index.php，API 入口为 public/api.php，路由入口为 public/router.php。
- 配置与插件
  - ThinkCMF 使用 data/config 作为配置目录；插件与安装包内存在各自 config.php，便于按需覆盖。
- 调试工具配置建议
  - 开发环境启用 trace 与详细日志；生产环境关闭 trace 并降低日志级别；Xdebug 仅在本地启用。

**章节来源**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)
- [public/router.php](file://public/router.php)