Ubuntu中PHPStorm的调试功能如何使用

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

一 环境准备与安装

• 确认 PHP 版本：运行命令查看版本与 SAPI（如 Apache 或 PHP-FPM）。
• 安装 Xdebug（适配你的 PHP 版本，如 php8.1-xdebug）：
  • 命令：sudo apt-get update && sudo apt-get install php-xdebug
• 重启服务使扩展生效：
  • Apache：sudo systemctl restart apache2
  • Nginx + PHP-FPM：sudo systemctl restart php{version}-fpm && sudo systemctl restart nginx
• 验证安装：
  • php -v（输出中应包含 with Xdebug）
  • php -m | grep xdebug（应能看到 xdebug）

二 配置 Xdebug 3（Ubuntu 常用）

• 编辑对应 SAPI 的 php.ini（路径示例：/etc/php/{version}/{apache2|fpm}/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.mode=debug 启用调试模式（Xdebug 3 推荐方式）
  • xdebug.client_host 为调试客户端（PhpStorm）地址，本地调试填 127.0.0.1
  • xdebug.client_port 默认 9003，需与 PhpStorm 一致
  • xdebug.start_with_request=yes 让每次请求都尝试连接调试器（也可用触发方式，见下文“常见问题”）
• 保存后重启 Web 服务（见上节命令）

三 配置 PhpStorm

• 设置 PHP 解释器：
  • File → Settings → Languages & Frameworks → PHP → Interpreter → 选择或添加 /usr/bin/php
• 配置 Servers（路径映射）：
  • File → Settings → Languages & Frameworks → PHP → Servers → “+”
  • Name：自定义；Host：localhost；Port：80/443
  • 勾选 Use path mappings，将本地项目路径映射到服务器路径（如本地 /var/www/html ↔ 服务器 /var/www/html）
• 配置调试运行项：
  • Run → Edit Configurations → “+” → PHP Web Page
  • Name：自定义；Server：选择上一步的 Server；Debugger：Xdebug
• 常用快捷键：
  • 开始/停止调试：Shift+F9 / Ctrl+F2
  • 单步执行：F8（Step Over）、F7（Step Into）、Shift+F8（Step Out）

四 开始调试与常用操作

• 在代码行号左侧点击设置断点（红色圆点）
• 点击工具栏绿色电话图标或按 Shift+F9 启动监听
• 浏览器访问目标页面（如 http://localhost/your_project/index.php），命中断点后自动暂停
• 在调试面板查看：
  • Variables：当前作用域变量
  • Call Stack：调用堆栈
  • 使用 F8/F7/Shift+F8 控制执行流程，观察变量与调用栈变化

五 常见问题与排查

• 端口冲突：
  • 避免使用已被 PHP-FPM 占用的 9000，推荐 9003
• 断点未命中：
  • 核对 Xdebug 与 PhpStorm 的端口一致（默认 9003）
  • 本地调试时 xdebug.client_host 应为 127.0.0.1
  • 确保 Web 服务已重启（Apache：sudo systemctl restart apache2；Nginx+PHP-FPM：sudo systemctl restart php{version}-fpm && sudo systemctl restart nginx）
  • 使用 php -m | grep xdebug 与 phpinfo() 检查 Xdebug 是否加载及配置是否生效
• 触发式调试（替代 start_with_request=yes）：
  • 将 xdebug.start_with_request 设为 trigger，访问时在 URL 添加参数：?XDEBUG_TRIGGER=1（或设置 Cookie），即可按需启动调试
• 路径映射错误导致变量/栈不可读：
  • 在 Servers 中正确设置本地与服务器路径映射（尤其使用虚拟机、容器或远程部署时）