Debian上PHP代码如何调试

Debian 上 PHP 代码调试实操指南

一 基础环境准备与错误可见性

• 开启错误报告（开发环境）：在对应的 php.ini（如 /etc/php/8.x/apache2/php.ini、/etc/php/8.x/fpm/php.ini、/etc/php/8.x/cli/php.ini）中设置：
  • error_reporting = E_ALL | E_STRICT
  • display_errors = On
• 生产环境建议：关闭页面显示错误，改为记录日志
  • display_errors = Off
  • log_errors = On
  • error_log = /var/log/php_errors.log
• 快速定位 php.ini：执行 php --ini 查看加载的配置文件与路径。
• 查看错误日志：
  • Apache：/var/log/apache2/error.log
  • Nginx/PHP-FPM：/var/log/nginx/error.log、/var/log/php/8.x-fpm.log
  • 实时查看：tail -f /var/log/…
• 代码级调试辅助：使用 error_log(“var=” . $var, 3, “/tmp/debug.log”); 输出关键变量与流程信息。

二 使用 Xdebug 进行断点调试（CLI 与 Web 均适用）

• 安装扩展（按 PHP 版本选择包名，如 php8.2-xdebug）：
  • sudo apt update
  • sudo apt install php-xdebug
• 配置 php.ini（建议统一在 [xdebug] 段落中配置，注意 CLI 与 FPM 各一份）：
  • zend_extension=xdebug.so
  • xdebug.mode=debug
  • xdebug.client_host=127.0.0.1
  • xdebug.client_port=9003
  • xdebug.start_with_request=yes
  • xdebug.idekey=PHPSTORM
• 重启服务：
  • Apache：sudo systemctl restart apache2
  • Nginx/PHP-FPM：sudo systemctl restart php8.x-fpm && sudo systemctl restart nginx
• 版本差异提示：
  • Xdebug 3.x 使用 xdebug.mode=debug、client_host/client_port 等新参数
  • Xdebug 2.x 常见为 remote_enable=1、remote_host/remote_port 等旧参数，若你的发行版提供的是 2.x，请按 2.x 语法配置
• 快速验证安装：php -v 应能看到 with Xdebug 字样。

三 IDE 联动调试步骤（PHPStorm 与 VS Code）

• PHPStorm
  • 启动监听：工具栏点击 Start Listening for PHP Debug Connections（电话图标）
  • 配置 Servers：File → Settings → Languages & Frameworks → PHP → Servers，新增服务器，填写 Host/Port，勾选 Use path mappings 并映射本地与服务器路径
  • 触发调试：浏览器访问对应 URL（可配合 XDEBUG_SESSION_START=PHPSTORM 或浏览器扩展触发），命中断点后查看变量、堆栈与单步执行
• VS Code
  • 安装扩展：PHP Debug（felixfbecker.php-debug）
  • 配置 launch.json（示例）： { “version”: “0.2.0”, “configurations”: [ { “name”: “Listen for Xdebug”, “type”: “php”, “request”: “launch”, “port”: 9003, “log”: true } ] }
  • F5 启动监听，浏览器访问触发断点。

四 命令行脚本与常见问题排查

• CLI 调试
  • 直接运行脚本：php your_script.php
  • 若脚本需要请求参数或浏览器 Cookie，可使用 curl 携带 XDEBUG_SESSION_START=PHPSTORM 触发调试：
    • curl -v http://localhost/test.php -H “Cookie: XDEBUG_SESSION=PHPSTORM”
• 常见问题
  • 端口被占用：lsof -iTCP:9003 -sTCP:LISTEN；更换 xdebug.client_port 或释放占用进程
  • 防火墙/SELinux：本地回环一般无碍；远程调试需放通 9003/tcp
  • 多 SAPI 配置不一致：确保 CLI/FPM/Apache 各自的 php.ini 都已启用 Xdebug 且端口一致
  • 路径映射错误：PHPStorm 中正确设置 Servers → Path mappings，否则断点无法命中
  • 旧版 Xdebug 配置混用：3.x 与 2.x 参数差异较大，避免混用导致不生效。

五 辅助工具与性能分析

• 快速输出与中断：使用 var_dump()/print_r()、die()/exit() 定位问题（仅开发环境）
• 可视化调试工具栏：PHP Debug Bar，便于查看 SQL、请求、性能等
• 性能分析：Blackfire 进行调用图、耗时与覆盖率分析（适合性能瓶颈定位）
• 异常与日志策略：合理使用 try-catch 与 error_log()，在关键路径记录上下文信息。