Ubuntu PHP调试如何进行

Ubuntu 下 PHP 调试实操指南

一 基础环境快速排查

• 定位配置文件与生效项：运行 php --ini 查看加载的 php.ini；CLI 与 Web 可能分别使用 /etc/php/<版本号>/cli/php.ini 与 /etc/php/<版本号>/apache2/php.ini（或 fpm/php.ini）。
• 开启错误报告与日志（开发环境）：在对应 php.ini 中设置
  • display_errors = On
  • error_reporting = E_ALL
  • log_errors = On
  • error_log = /var/log/php_errors.log（确保 PHP 进程对该路径有写权限）
• 重启服务使配置生效：
  • Apache：sudo systemctl restart apache2
  • PHP-FPM：sudo systemctl restart php<版本号>-fpm
  • Nginx 场景需同时重启 Nginx：sudo systemctl restart nginx
• 实时查看错误日志：
  • Apache：sudo tail -f /var/log/apache2/error.log
  • Nginx：sudo tail -f /var/log/nginx/error.log
• 快速验证扩展与配置：
  • 查看是否加载 Xdebug：php -m | grep xdebug
  • 查看完整配置：phpinfo();
    以上步骤能在不依赖调试器的情况下，快速获得错误类型、行号与调用栈信息。

二 使用 Xdebug 进行断点调试

• 安装 Xdebug（适配你的 PHP 版本，如 php8.1 则安装 php8.1-xdebug）：
  • sudo apt-get update && sudo apt-get install php-xdebug
• 配置 php.ini（建议以独立节添加，避免与旧参数混用）：
  • Xdebug 3（推荐）：
    • zend_extension=xdebug.so
    • xdebug.mode=debug
    • xdebug.client_host=127.0.0.1
    • xdebug.client_port=9003
    • xdebug.start_with_request=yes（浏览器访问即触发调试；CLI 调试可用 xdebug.start_with_request=trigger 并通过 XDEBUG_TRIGGER 环境变量触发）
  • Xdebug 2（旧环境，如 Ubuntu 16.04 常见）：
    • zend_extension=xdebug.so
    • xdebug.remote_enable=1
    • xdebug.remote_host=localhost
    • xdebug.remote_port=9003
    • xdebug.remote_handler=dbgp
    • xdebug.remote_mode=req
    • xdebug.remote_autostart=1
• 重启服务：
  • Apache：sudo systemctl restart apache2
  • PHP-FPM：sudo systemctl restart php<版本号>-fpm
• IDE 配置（以 PhpStorm 为例）：
  • 设置 CLI 解释器：File > Settings > Languages & Frameworks > PHP > CLI Interpreter
  • 配置服务器：PHP > Servers 新增主机与端口（如 localhost:80），设置本地与服务器目录映射（Path Mappings）
  • 启动监听（电话图标），在代码行号处设置断点，浏览器访问触发调试
• 浏览器辅助（可选）：安装 Xdebug Helper 扩展，IDE Key 设为 PHPSTORM，点击“Debug”后访问页面即可连上调试器
  以上流程覆盖 Xdebug 3 与 Xdebug 2 的主流用法，并给出 PhpStorm 的关键配置点。

三 命令行脚本与 VS Code 调试

• VS Code 安装扩展：在扩展市场安装 PHP Debug（作者 Felix Becker）。
• 生成调试配置：在 VS Code 打开项目，进入 Run and Debug，点击齿轮生成 .vscode/launch.json，示例：
  • 监听模式（配合浏览器或触发变量）：
    • {
      “version”: “0.2.0”,
      “configurations”: [
      {
      “name”: “Listen for Xdebug”,
      “type”: “php”,
      “request”: “launch”,
      “port”: 9003,
      “pathMappings”: {
      “/var/www/html”: “${workspaceFolder}”
      }
      }
      ]
      }
  • CLI 调试（直接运行脚本）：
    • {
      “name”: “Launch currently open script”,
      “type”: “php”,
      “request”: “launch”,
      “program”: “${file}”,
      “cwd”: “${fileDirname}”,
      “port”: 9003
      }
• 触发方式：
  • Web 请求：确保 xdebug.start_with_request=yes 或设置环境变量 XDEBUG_TRIGGER=1 后访问页面
  • CLI 脚本：使用 XDEBUG_TRIGGER=1 php your_script.php 启动
• 注意路径映射：将服务器路径（如 /var/www/html）映射到本地工作区，否则断点可能不生效。

四 常见问题与排查清单

• 端口被占用：检查 9003 是否被其他进程占用（如 sudo lsof -i :9003），必要时更换端口并同步 IDE 与 php.ini 配置。
• 配置未生效：确认修改的是实际加载的 php.ini（用 php --ini 与 phpinfo(); 双重核对），并重启 Apache/PHP-FPM。
• 防火墙与网络：本机回环 127.0.0.1 通常不受限；如远程调试，确保 client_host 可达且端口开放。
• 路径映射错误：CLI 与 Web 的根目录可能不同，务必在 IDE 的 Servers 中正确设置 pathMappings。
• 性能与日志：Xdebug 会显著降低执行速度，建议仅在开发环境启用；生产环境关闭 display_errors，仅保留 log_errors 与合适的 error_log。