PHP代码在Ubuntu如何调试

Ubuntu下PHP调试实操指南

先说一个很常见的场景：你在Ubuntu上写PHP代码，写完了想看看变量对不对、逻辑跑没跑通，结果要么只能在浏览器里print_r，要么一脸懵不知道错在哪。其实调试这件事，方法摆在那，关键在于怎么搭环境、用什么工具、遇到坑怎么跳过去。下面把这套流程拆开讲清楚。

一 环境准备与版本确认

不管用哪种调试方式，先搞清楚你手头的PHP版本和运行模式。命令行里敲php -v看看版本号，再用php -m | grep -i xdebug确认Xdebug装没装。别忘了，CLI和Web环境用的是不同的php.ini——通过php --ini能准确看到当前SAPI加载的配置文件位置，改的时候要对号入座。如果打算远程调试（比如IDE跑在本机、PHP在远端容器里），记得把Ubuntu的防火墙和云安全组放行调试端口，默认是9003。

二 使用 Xdebug 3 进行断点调试（推荐）

说到断点调试，Xdebug 3是目前最主流的选择。安装很简单，Ubuntu 20.04/22.04上直接sudo apt-get update && sudo apt-get install php-xdebug就行——不过最好确认一下它匹配你的PHP版本（7.4/8.0/8.1/8.2/8.3都没问题）。装完之后，在对应的php.ini末尾加上这几行关键配置：

• 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（保持和IDE一致）

改完之后重启服务：Apache用sudo systemctl restart apache2，Nginx+PHP-FPM则分别重启php{version}-fpm和nginx。接下来配IDE——VS Code在.vscode/launch.json里加一个监听Xdebug的配置，端口9003，路径映射把服务器上的/var/www/html映射到本地工作区。PhpStorm更直接：设置里把Debug端口改成9003，调试器选Xdebug，然后直接用“Run/Debug”跑CLI脚本。触发调试时，浏览器访问对应URL或者命令行执行脚本，断点就会卡住，你就能盯着变量、调用栈、单步走了。

三 无调试器的快速定位方法

有时候环境实在不方便装Xdebug，或者就想快速看一下某个值，那老办法还是管用的。临时输出用var_dump($var); print_r($var); exit;；想写日志就用error_log('msg', 0)，或者指定文件error_log('msg', 3, '/var/log/php_app.log')。开发环境下，把php.ini里的错误报告开到最狠：error_reporting=E_ALL，display_errors=On（生产环境一定要关掉），log_errors=On，error_log指向一个可写的路径，比如/var/log/php_errors.log。顺手验证一下：故意造个语法错误，看看日志文件里有没有内容——有就说明配置生效了。

四 常见问题与排查清单

调试不出结果的时候，别慌，按这个顺序过一遍。先查端口9003有没有被占用，ss -lntp | grep 9003看一眼，被占了就换个端口，两边同步改。然后确认你改的php.ini确实是对应SAPI的——CLI和FPM是两套配置文件，改完必须重启对应的服务。路径映射是VS Code用户最容易栽的地方，服务器上的/var/www/html和本地文件夹得一一对应，差一个斜杠都不行。远程调试的话，防火墙和安全组要放行9003；本机回环则不用。最后，如果看到xdebug.remote_enable这种老参数，说明你还在用Xdebug 2——赶紧升级到Xdebug 3，参数体系完全变了。

五 进阶建议

调试只是第一步。想让代码更稳，建议引入PHPUnit做单元测试，回归和边界情况都能覆盖。性能方面，Xdebug的profile模式打开后，配合工具能清晰看瓶颈在哪——但注意只在开发环境用，别在生产上开。