Ubuntu 下使用 PHPStorm 高效调试 PHP 代码
一 环境准备与 Xdebug 安装
- 安装 PHP 与 Xdebug（适配你的 PHP 版本，如 7.4/8.0/8.1/8.2/8.3）：
- 安装解释器与常用工具：sudo apt-get install php php-cli php-dev
- 安装 Xdebug（示例为 8.1）：sudo apt-get install php8.1-xdebug
- 确认扩展已加载：php -m | grep xdebug（应看到 xdebug）
- 注意 CLI 与 FPM/Apache 可能使用不同的 php.ini，调试前分别确认加载的配置路径与生效的扩展。
二 本机调试配置步骤
- 配置 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
- 可选：xdebug.idekey=PHPSTORM
- 重启服务：
- Apache：sudo systemctl restart apache2
- PHP-FPM：sudo systemctl restart php**{version}**-fpm
- PHPStorm 设置：
- 解释器：File → Settings → Languages & Frameworks → PHP → CLI Interpreter，选择 /usr/bin/php
- 服务器：Languages & Frameworks → PHP → Servers → +，填写 Name/Host，端口 80/443，Debugger 选 Xdebug，并设置本地与服务器代码的路径映射（关键）
- 调试端口：Languages & Frameworks → PHP → Debug，确保 Debug port=9003
- 开始调试：
- 在代码行号左侧点下断点
- 工具栏点击“电话听筒”图标开始监听（Start Listening for PHP Debug Connections）
- 浏览器访问对应页面，命中断点后可在 IDE 查看变量、调用栈并单步执行。
三 远程与容器调试要点
- 服务器（Ubuntu 远程/虚拟机/Vagrant）php.ini（Xdebug 3）：
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=宿主机的局域网 IP（如 192.168.1.10），勿用 127.0.0.1
- xdebug.client_port=9003
- xdebug.start_with_request=yes
- 可选：xdebug.idekey=PHPSTORM
- PHPStorm：
- Servers 中新建服务器，填写远程 Host/Port，并精确配置本地路径 ↔ 服务器路径映射
- Run → Edit Configurations → 新建 PHP Web Page，选择服务器与浏览器
- 触发会话（二选一）：
- 在 URL 附加参数：?XDEBUG_SESSION_START=PHPSTORM
- 使用浏览器扩展或书签启动调试会话（IDE Key 保持一致）
- 常见问题速解：
- 端口不通：在服务器与宿主机放行 9003/TCP；云主机需配置安全组
- 断点不生效：检查路径映射、client_host 是否指向宿主 IP、Xdebug 是否加载到正确的 php.ini
- 多开发者环境：避免用 connect_back，统一用 idekey 与会话触发。
四 效率提升与常见问题排查
- 提升效率的小技巧：
- 使用“电话听筒”常开监听，配合 URL 参数按需触发，减少频繁开关调试
- 善用断点条件、日志点与“Evaluate Expression”快速定位问题
- 框架项目优先用框架的入口（如 public/index.php）创建调试配置，减少路由未命中
- 替代大量 var_dump：用断点+变量/栈视图观察，减少代码污染与信息泄露风险
- 快速自检清单：
- php -m | grep xdebug 有输出
- php.ini 中 zend_extension 路径正确且只加载一次
- Debug port 在 php.ini 与 PHPStorm 一致（默认 9003）
- Servers 的路径映射正确（本地与服务器绝对路径一一对应）
- 监听已开启且访问时携带 XDEBUG_SESSION_START=PHPSTORM 或扩展已激活会话。