Ubuntu PHP脚本怎么调试

在 Ubuntu 上调试 PHP 脚本，最趁手的工具莫过于 Xdebug。很多刚接触的朋友会觉得配置起来有点麻烦，其实只要理清几个关键步骤，整个过程比想象中要顺畅得多。下面就把这套流程拆开来聊一聊。

安装 Xdebug

首先打开终端，执行一条命令就能搞定：

sudo apt-get update
sudo apt-get install php-xdebug

系统会自动匹配你当前 PHP 版本的 Xdebug 扩展。如果提示找不到包，可能需要先确认一下 PHP 版本对应的源是否已启用——不过大部分 Ubuntu 官方源都直接包含。

配置 Xdebug

装好之后，得告诉 PHP 怎么用它。找到 php.ini 文件，不同环境对应的位置不太一样：

• 命令行版本：/etc/php/7.x/cli/php.ini
• Apache 版本：/etc/php/7.x/apache2/php.ini
• Nginx/PHP-FPM 版本：/etc/php/7.x/fpm/php.ini

把 7.x 换成你实际安装的 PHP 版本号就行。在文件末尾添加以下内容：

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

这里用的是 PHPStorm 默认的 IDE Key，如果你用其他编辑器（比如 VS Code 或 Sublime），记得把 PHPSTORM 改成对应的 key。端口号 9003 是 Xdebug 3.x 的默认值，也请确认你的 IDE 里设置的调试端口是否一致。

重启 Web 服务器

改完配置，得让服务重新加载才能生效。根据你的环境选择对应命令：

# Apache
sudo systemctl restart apache2

# Nginx + PHP-FPM
sudo systemctl restart php7.x-fpm
sudo systemctl restart nginx

同样，把 7.x 替换成你的 PHP 版本。

配置 IDE

以 PHPStorm 为例，打开设置（File → Settings），找到 Languages & Frameworks → PHP → Debug，确保 Xdebug 部分的 Debug port 填的是 9003（或者你之前指定的端口）。其他 IDE 的操作逻辑类似，都是设置一个监听端口，与 php.ini 里的 client_port 对应起来。

开始调试

一切就绪后，在 PHP 代码里打上断点，用 IDE 启动调试会话。当请求执行到断点处，调试器会自动暂停，这时候就能查看变量、单步跟踪、甚至修改运行时的值——排查问题的效率会高出一大截。

如果是在 Docker 容器里跑 PHP 应用，需要额外注意网络配置：容器内的 Xdebug 要能连上宿主机的 IDE，通常设置 xdebug.client_host 为宿主机的内网 IP 或 host.docker.internal（Windows/Mac 下支持）。这一点很容易踩坑，提前留个心眼就好。