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()，在关键路径记录上下文信息。
