Ubuntu PHP调试如何进行

Ubuntu 下 PHP 调试实操指南

一 基础环境快速排查

调试的第一步，永远是确保环境本身“健康”。很多看似复杂的问题，其实根源在于基础配置没到位。咱们先花几分钟，把环境快速过一遍。

定位配置文件与生效项：这事儿可不能想当然。最直接的办法是运行 php --ini，看看系统到底加载了哪个配置文件。这里有个关键细节：命令行（CLI）和Web服务（如Apache或Nginx）用的php.ini很可能是两个不同的文件。通常，它们分别位于 /etc/php/<版本号>/cli/php.ini 和 /etc/php/<版本号>/apache2/php.ini（如果用的是PHP-FPM，则可能是fpm/php.ini）。搞混了，后续所有配置都白搭。

开启错误报告与日志（开发环境）：在开发阶段，让错误“无处遁形”至关重要。找到正确的php.ini后，确保以下几项已经设置好：

• display_errors = On（让错误直接显示在页面上）
• error_reporting = E_ALL（报告所有级别的错误）
• log_errors = On（同时记录到日志）
• error_log = /var/log/php_errors.log（指定日志路径，别忘了给PHP进程对这个路径的写入权限）

重启服务使配置生效：修改完配置，不重启服务等于没改。根据你的Web服务器来操作：

• Apache：sudo systemctl restart apache2
• PHP-FPM：sudo systemctl restart php<版本号>-fpm
• 如果用的是Nginx，它本身不解析PHP，所以需要同时重启Nginx和PHP-FPM：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调试的行业标准，能让你像调试本地应用一样，逐行跟踪代码执行。不过，它的配置因版本而异，咱们分版本说清楚。

安装 Xdebug：首先，确保安装的版本与你的PHP版本匹配。例如，PHP 8.1就安装php8.1-xdebug。命令很简单：sudo apt-get update && sudo apt-get install php-xdebug。系统通常会为你匹配当前PHP版本对应的包。

配置 php.ini：这是核心环节。强烈建议在php.ini末尾以独立区块添加Xdebug配置，避免和原有参数混淆。

• 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（设置为yes后，任何浏览器访问都会触发调试；如果是调试命令行脚本，可以设为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

重启服务：配置保存后，别忘了重启对应的Web服务（Apache或PHP-FPM），让改动生效。

IDE 配置（以 PhpStorm 为例）：服务器端准备好了，IDE这边也得对接上。关键几步：

1. 设置CLI解释器：进入 File > Settings > Languages & Frameworks > PHP > CLI Interpreter，添加你的PHP解释器路径。
2. 配置服务器映射：在 PHP > Servers 里新增一个服务器，填写主机（如localhost）和端口（如80）。最关键的一步是设置路径映射（Path Mappings），将服务器上的项目路径（如/var/www/html）准确映射到本地工作区的目录。
3. 启动调试：点击工具栏上的“电话”图标启动监听，然后在代码行号旁点击设置断点。最后用浏览器访问你的页面，调试会话就会自动触发并停在断点处。

浏览器辅助（可选）：为了更灵活地控制调试会话，可以在浏览器（如Chrome）安装“Xdebug Helper”这类扩展。将IDE Key设置为PHPSTORM，之后在需要调试的页面上点击扩展图标选择“Debug”模式，再刷新页面即可。

以上流程基本覆盖了Xdebug 3与Xdebug 2的主流用法，并给出了PhpStorm中的关键配置点。按图索骥，就能建立起完整的断点调试环境。

三 命令行脚本与 VS Code 调试

不是所有PHP代码都跑在Web服务器里。后台脚本、定时任务、命令行工具同样需要调试。这时，VS Code凭借其轻量和强大的扩展生态，成了很多开发者的新选择。

VS Code 安装扩展：第一步，在VS Code的扩展市场中搜索并安装“PHP Debug”（作者是Felix Becker）。这是官方推荐的调试扩展，能无缝对接Xdebug。

生成调试配置：打开你的PHP项目，进入“运行和调试”（Run and Debug）面板，点击齿轮图标，VS Code会为你生成一个.vscode/launch.json配置文件。里面通常需要两种配置：

• 监听模式（用于Web请求或按需触发）：

  {
    "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请求：确保php.ini中xdebug.start_with_request=yes，或者通过设置环境变量XDEBUG_TRIGGER=1，然后访问页面。
• CLI脚本：直接在终端使用XDEBUG_TRIGGER=1 php your_script.php来启动脚本，调试器便会介入。

注意路径映射：这里有个常见的坑：如果服务器上的项目路径（例如/var/www/html）没有正确映射到VS Code打开的工作区文件夹，那么断点将永远不会生效。务必在pathMappings里检查这一点。

四 常见问题与排查清单

调试环境搭建很少一帆风顺。下面这份排查清单，收录了最常见的问题和解决思路，遇到麻烦时不妨先对照看看。

• 端口被占用：Xdebug默认使用9003端口。如果连接失败，先用sudo lsof -i :9003检查该端口是否已被其他进程（如旧版的PHP-FPM）占用。如果是，要么停止占用进程，要么在php.ini和IDE的调试配置中同步修改为另一个端口。
• 配置未生效：这是最典型的问题。请用php --ini和创建一个phpinfo()页面进行双重核对，确认你修改的php.ini文件正是当前PHP环境实际加载的那一个。确认无误后，务必重启Apache或PHP-FPM服务。
• 防火墙与网络：本地调试（127.0.0.1）通常不受影响。但如果涉及远程调试（从本地IDE调试服务器上的代码），务必确保php.ini中的client_host设置为可访问的服务器IP，并且服务器防火墙开放了对应的调试端口。
• 路径映射错误：断点无法命中的头号元凶。记住，通过命令行执行和通过Web服务器访问，脚本的“当前工作目录”可能完全不同。必须在IDE（如PhpStorm的Servers设置或VS Code的pathMappings）中，将服务器端的绝对路径精确映射到本地项目目录。
• 性能与日志：最后给个重要提醒：Xdebug会显著降低PHP的执行速度，因此务必仅在开发环境启用。在生产环境，必须关闭display_errors（避免暴露敏感信息），但可以开启log_errors并将error_log指向一个安全的路径，以便记录问题而不影响用户。