PHPStorm在Ubuntu上如何调试PHP代码

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

一 环境准备

• 安装 PHP 与 Xdebug（CLI 与 FPM 各一份，保持版本一致）：
  • 更新索引并安装：sudo apt update && sudo apt install php php-xdebug
  • 若系统存在多版本，请安装对应版本包，例如：sudo apt install php8.1-xdebug
• 确认 CLI 的 PHP 可执行文件路径（后续在 PhpStorm 中要用）：which php（常见为：/usr/bin/php）
• 可选：安装并启动 Web 服务（Apache 或 Nginx + PHP-FPM），用于 Web 请求调试

二 配置 Xdebug 3（Ubuntu 20.04+ 与 Xdebug 3.x 推荐）

• 找到并编辑对应 SAPI 的 php.ini（常见路径，按你的版本替换 {php_version}）：
  • CLI：/etc/php/{php_version}/cli/php.ini
  • FPM：/etc/php/{php_version}/fpm/php.ini
  • Apache：/etc/php/{php_version}/apache2/php.ini
• 在 php.ini 的 [xdebug] 段落加入或调整为（端口保持与 PhpStorm 一致，示例为 9003）：
  • 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
• 重启服务使配置生效：
  • FPM：sudo systemctl restart php{php_version}-fpm
  • Apache：sudo systemctl restart apache2
  • Nginx：sudo systemctl restart nginx
• 验证 Xdebug 已启用：php -v 应能看到 “with Xdebug v3.x”

三 配置 PhpStorm

• 设置 PHP 解释器：File → Settings → Languages & Frameworks → PHP → CLI Interpreter，选择或添加 /usr/bin/php
• 配置 Servers：File → Settings → Languages & Frameworks → PHP → Servers → +，填写
  • Name：任意（如：localhost）
  • Host：localhost（或你的域名/IP）
  • Port：80/443
  • Debugger：Xdebug
  • 勾选 “Use path mappings”（若项目在虚拟机/容器/远程，需将本地项目路径映射到服务器路径）
• 配置 Debug 端口：File → Settings → Languages & Frameworks → PHP → Debug，确保 Debug port 为 9003
• 创建运行/调试配置：Run → Edit Configurations → + → PHP Web Page
  • Name：自定义
  • Server：选择上一步的服务器
  • Start URL：要调试的页面（如：/index.php 或 /info.php）
• 设置断点：在代码行号左侧单击，出现红点

四 开始调试

• Web 调试（Apache/Nginx + FPM）
  • 在 PhpStorm 中点击工具栏的绿色虫子图标或按 Shift+F9 启动监听
  • 浏览器访问你的页面，若未自动触发，可在 URL 后追加参数：?XDEBUG_SESSION_START=PHPSTORM
  • 命中断点后，可查看变量、调用栈，并使用 F7/F8/Shift+F8 控制执行
• CLI 调试（命令行脚本）
  • 在 PhpStorm 中创建运行/调试配置，类型选 PHP Script，指定脚本路径
  • 直接点击调试运行，脚本会在断点处暂停
• 浏览器便捷触发（可选）
  • 安装浏览器扩展 Xdebug Helper，将 IDE key 设为 PHPSTORM，点击图标开启调试会话

五 常见问题排查

• 端口被占用：lsof -i :9003 查看占用进程并关闭，或改为其他端口（需与 php.ini 和 PhpStorm 一致）
• 断点不被命中
  • 确认访问的是 FPM 对应的站点（而非直接 CLI 执行）
  • 检查 Servers 的 Host/Port/路径映射是否正确
  • 确认 Xdebug 配置为 xdebug.mode=debug 且 client_host/client_port 正确
• 多版本 PHP：确保 CLI、FPM、php.ini、PhpStorm 解释器选择的是同一 {php_version}
• 日志定位
  • Web 服务错误：journalctl -u apache2 或 journalctl -u nginx
  • Xdebug 日志：在 php.ini 增加 xdebug.log=/tmp/xdebug.log 并重启服务，查看连接与握手过程