Debian如何调试ThinkPHP应用

Debian 上调试 ThinkPHP 应用的实用流程

一 环境准备与错误可见性

• 安装调试扩展与常用工具（Debian 常用命令）
  • 安装 Xdebug（用于断点调试/远程调试）
    • apt 安装：sudo apt-get install php-xdebug
    • 或 pecl 安装：pecl install xdebug，然后在 php.ini 中加载扩展
  • 安装与启用常用工具：sudo apt-get install php-cli php-curl php-mbstring php-xml
• 配置 PHP 错误报告（开发环境）
  • 编辑 php.ini（Debian 常见路径：/etc/php//cli/php.ini 与 /etc/php//fpm/php.ini）
    • display_errors = On
    • error_reporting = E_ALL
    • log_errors = On
  • 重启服务：sudo systemctl restart apache2 或 sudo systemctl restart php*-fpm
• 目录与权限
  • 确保应用目录可写：sudo chown -R www-data:www-data /var/www/your-app/runtime
  • 如使用 Nginx+PHP-FPM，确认 FPM 运行用户与目录属主一致

二 开启框架调试与页面 Trace

• ThinkPHP 5/6 常用做法
  • 入口文件 index.php 定义常量：define(‘APP_DEBUG’, true); （仅开发环境）
  • 配置文件 config/app.php 中设置：‘debug’ => true
  • 页面 Trace：在配置中开启 ‘show_page_trace’ => true（ThinkPHP5）；TP6 可在调试配置中启用页面 Trace 或按需使用开发者工具栏
• ThinkPHP 3.2 常用做法
  • 入口文件：define(‘APP_DEBUG’, true);
  • 配置文件（如 Common/Conf/config.php）中开启：‘SHOW_PAGE_TRACE’ => true
• 作用与提示
  • 开启调试模式后，系统会输出更详细的错误信息、关闭模板缓存、记录 SQL、便于定位问题
  • 页面 Trace 可在浏览器右下角查看请求、SQL、运行时间等信息；若未显示，确认当前请求确实渲染了页面（如调用了 display 或对应的输出方法）

三 日志与 SQL 调试

• ThinkPHP 6 日志（基于 Monolog）
  • 写入日志：
    • use think\facade\Log;
    • Log::info(‘业务开始’, [‘uid’ => 1]);
    • Log::error(‘异常’, [‘exception’ => $e-> getMessage()]);
  • 查看日志：
    • 文件路径：项目 runtime/log/ 目录，按日期分文件
    • 命令行查看：php think list log（列出日志通道/文件）
  • 配置要点（config/app.php 的 log 项）：
    • type：file/socket/trace/none
    • path：日志目录（默认 runtime/log）
    • level：记录级别（debug/info/notice/warning/error/critical/alert/emergency）
    • single/file_size/time_format/json 等按需调整
• ThinkPHP 3.2 日志
  • 开启全量记录：在 Common/Conf/config.php 中
    • ‘LOG_RECORD’ => true,
    • ‘LOG_LEVEL’ => ‘EMERG,ALERT,CRIT,ERR,notice,info,debug’
  • 默认日志目录：/Application/Runtime/Logs
• SQL 与性能
  • 开启 SQL 日志（TP5/6 可在数据库配置中开启，或在调试配置中记录 SQL）
  • 获取最近一次 SQL：使用模型的 getLastSql() 方法，便于定位慢查询与绑定参数问题
  • 代码段耗时：使用 debug_start(‘label’) / debug_end(‘label’) 输出区间耗时与内存

四 断点调试与变量观察（Xdebug + IDE）

• 配置 php.ini 的 Xdebug（示例，按实际版本调整）
  • zend_extension=xdebug.so
  • xdebug.mode=debug
  • xdebug.start_with_request=yes 或 trigger（配合浏览器插件触发）
  • xdebug.client_host=127.0.0.1
  • xdebug.client_port=9003
  • xdebug.log=/var/log/php-xdebug.log
• IDE 设置（如 PhpStorm/VSCode）
  • 配置服务器解析路径（将服务器根目录映射到项目根目录）
  • 创建 Run/Debug 配置，选择 PHP Web Application
• 调试步骤
  • 在 IDE 中设置断点，浏览器访问对应 URL（或使用触发方式）
  • 请求命中后自动中断，可查看调用栈、变量、单步执行、观察表达式
• CLI 调试
  • 命令行执行：php -dxdebug.mode=debug -dxdebug.start_with_request=yes your-script.php
  • 或在代码中临时触发：xdebug_break();

五 常见问题快速排查清单

• 页面空白或无输出
  • 确认已开启 APP_DEBUG 与 PHP 错误显示；查看 runtime/log 与 php-fpm/apache 错误日志
  • 检查语法错误、函数未定义、类未找到等导致脚本提前终止的情况
• 404 控制器或方法不存在
  • 核对 URL 路由、控制器/方法命名与大小写（Linux 区分大小写）
• 数据库连接失败
  • 核对 database.php 配置（host、port、dbname、user、password、charset）
  • 确认数据库服务运行、远程访问权限与防火墙策略
• SQL 错误或性能问题
  • 开启 SQL 日志，使用 getLastSql() 复核最终 SQL 与绑定参数
  • 为慢查询添加索引，必要时使用 explain 分析执行计划
• 页面 Trace 不显示
  • 确认当前请求确实渲染了页面（如调用 display 或对应输出方法），以及配置中已开启 Trace

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！