Debian 下调试 ThinkPHP 的实用流程
一 基础环境与错误可见性
- 开启调试模式：在项目的配置中打开调试，例如在 .env 或 config.php 中设置 APP_DEBUG=true。注意 .env 仅用于本地开发，部署到生产会被忽略。调试模式会输出详细错误与堆栈，便于定位问题。
- 查看日志：优先查看框架日志 runtime/log/，同时结合 Nginx/Apache 错误日志（如 /var/log/nginx/error.log 或 /var/log/apache2/error.log）排查 Web 层问题。
- 命令行运行：开发阶段可直接用 php think run 启动内置服务器，实时观察输出与异常，适合接口与命令行任务调试。
二 内置调试工具与常用技巧
- 变量输出：使用 dump($var, true, ‘label’, true); 打印结构化变量，便于在浏览器或控制台查看。
- 性能分析：用 debug_start(‘label’) / debug_end(‘label’) 记录代码段执行时间与内存占用，定位性能瓶颈。
- 页面 Trace：开启页面 Trace 或在代码中 trace(‘key’, $value)，快速查看执行流程、变量与 SQL 执行情况。
- SQL 日志：开启 SQL_DEBUG_LOG 记录每条 SQL 及其耗时，辅助排查慢查询与错误查询。
三 Xdebug 断点调试步骤
- 安装与启用：在 Debian 上为当前 PHP 版本安装 Xdebug（如通过 apt 或 pecl），并在 php.ini 中启用扩展。
- 关键配置示例（适配新版 Xdebug 3，端口示例为 9003）：
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/var/log/php/xdebug.log
如仍使用旧版（Xdebug 2），可用：[xdebug]
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9003
xdebug.remote_autostart=1
- IDE 设置：在 PhpStorm 或 VS Code 中创建 PHP Remote Debug 配置，指定服务器与端口 9003，启动监听后访问对应 URL 触发断点。
- 命令行调试：也可在 CLI 下临时启用调试，例如：
php -dxdebug.mode=debug -dxdebug.start_with_request=yes your_script.php
以上步骤可实现断点、单步、变量与调用栈的直观调试。
四 Web 服务器与常见问题排查
- Web 服务配置要点：确保 Nginx/Apache 正确将 .php 请求转发给 PHP-FPM，例如 Nginx 使用 fastcgi_pass unix:/run/php/php7.4-fpm.sock; 或对应端口，避免因转发错误导致无法命中断点或无响应。
- 日志优先：遇到空白页或 500 错误，先查 runtime/log/ 与 Web 服务错误日志，从报错栈定位到具体文件与行号。
- 环境差异：Linux 环境注意文件大小写敏感与路径大小写一致，避免因部署差异引发“类不存在/找不到模板”等问题。
- 安全提醒：调试完成后务必关闭 APP_DEBUG，防止敏感信息泄露与性能受影响。