Ubuntu环境下phpstorm如何调试PHP代码

Ubuntu下使用 PhpStorm 调试 PHP 的完整步骤

一环境准备

安装 PHP 与 Xdebug（CLI 与 FPM 建议一致，避免调试不一致）：
- 更新索引并安装：sudo apt update && sudo apt install php php-xdebug
确认 CLI 的 php.ini 路径（后面会用到）：php -i | grep ‘Configuration File’
若使用 Nginx + PHP-FPM，确保 FPM 正在运行：sudo systemctl status php*-fpm
在 PhpStorm 中确认已识别 PHP 解释器：File → Settings → Languages & Frameworks → PHP（应显示已发现的 CLI 解释器）

二配置 Xdebug 3（Ubuntu 20.04+ 常见）

编辑 CLI 与 FPM 各自的 php.ini（路径形如：/etc/php/{php_version}/cli/php.ini 与 /etc/php/{php_version}/fpm/php.ini），在末尾添加或修改：
```
[xdebug]
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
```
- 说明：Xdebug 3 使用 client_host/client_port 与 start_with_request；如使用旧版 Xdebug 2，常见为 remote_enable/remote_host/remote_port 等参数，请勿混用两套配置。
重启服务使配置生效：
- Apache：sudo systemctl restart apache2
- Nginx + PHP-FPM：sudo systemctl restart php**{php_version}**-fpm && sudo systemctl restart nginx
可选验证：php -v 应能看到 Xdebug 字样；或创建 phpinfo.php 查看是否加载 Xdebug。

三在 PhpStorm 中完成调试配置

配置 Servers：File → Settings → Languages & Frameworks → PHP → Servers → +，填写
- Name：自定义（如：localhost）
- Host：localhost（或你的域名/IP）
- Port：80/443
- Debugger：Xdebug
- 路径映射（Path mappings）：将项目根目录映射到服务器根目录（如：/home/user/project → /var/www/html）
配置 Debug 端口：File → Settings → Languages & Frameworks → PHP → Debug，确保 Debug port 为 9003（与 xdebug.client_port 一致）
创建运行/调试配置：Run → Edit Configurations → + → PHP Web Page
- Server：选择上一步的服务器
- URL：如 http://localhost/index.php
- 勾选 “Break at first line in PHP scripts”（可选，便于确认调试是否生效）
启动调试：点击工具栏的绿色虫子图标或 Run → Debug，访问对应 URL，命中断点后即可查看变量、调用栈与单步执行。

四远程调试与常见问题

远程服务器场景（如本机运行 PhpStorm，调试虚拟机/容器/另一台主机上的 PHP）
- 在远程服务器 php.ini 中设置：
```
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=你的本机IP（可从远程访问到）
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.idekey=PHPSTORM
```
- 在 PhpStorm：Run → Start Listening for PHP Debug Connections；浏览器访问时在 URL 后附加参数：?XDEBUG_SESSION_START=PHPSTORM，或使用浏览器插件（如 Xdebug Helper）一键开启调试会话。
- 如存在防火墙/安全组，请放行 9003 端口；Docker 场景需将 client_host 指向宿主机（常见为 host.docker.internal 或宿主机局域网 IP），并确保端口映射正确。
常见问题快速排查
- 端口占用：lsof -i:9003 检查谁在占用；必要时更换端口并同步 php.ini 与 PhpStorm 设置。
- 未命中断点：确认访问的是 FPM 处理的请求（非 CLI）；检查 Servers 的路径映射是否正确；确认 Debug port 一致；查看 PhpStorm 的 Event Log 是否有 “Incoming Connection” 提示。
- Xdebug 版本混淆：Xdebug 2 与 3 配置项不同，建议统一升级到 3 并按上文配置；用 php -v 与 phpinfo() 双重确认加载的扩展与参数。

最新问答