在 Ubuntu 上把 Xdebug 与 PhpStorm 集成，按下面 5 步即可完成
一 安装 Xdebug 扩展
- 更新索引并安装与当前 PHP 版本匹配的扩展（常见包名为：php-xdebug 或 php{version}-xdebug）：
- 查看版本：php -v
- 安装示例：sudo apt-get update && sudo apt-get install php-xdebug
- 验证安装：php -m | grep xdebug 或 php -v 输出中应包含 with Xdebug。如未加载，检查是否安装到正确 SAPI（CLI/FPM/Apache）。
二 配置 Xdebug 参数
- 编辑对应 SAPI 的配置文件（路径随 PHP 版本与运行方式不同，常见为：/etc/php/{version}/{sapi}/php.ini；也可在 /etc/php/{version}/mods-available/xdebug.ini 中统一配置后软链启用）。推荐仅对 Web 请求启用调试，避免 CLI 交互受影响：
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=127.0.0.1
- xdebug.client_port=9003
- xdebug.start_with_request=trigger ; 浏览器访问时在 URL 添加 ?XDEBUG_TRIGGER 触发调试
- 说明：
- 端口 9003 为 Xdebug 3 默认；如与 php-fpm 冲突，可改为其他端口（如 9000），并同步修改 PhpStorm 的监听端口。
- 远程/容器调试时，将 client_host 改为宿主机或容器可达的 IP。
三 配置 PhpStorm
- 设置 PHP 解释器：File > Settings > Languages & Frameworks > PHP > Interpreters，选择 /usr/bin/php（或相应版本）。
- 配置 Servers：Languages & Frameworks > PHP > Servers > +，填写 Name、Host（如 localhost）、Port（如 80/443），勾选 Use path mappings，将本地项目路径映射到服务器路径（如本地 /var/www/html 映射到服务器 /var/www/html）。
- 配置 Debug：Languages & Frameworks > PHP > Debug，确保启用 Xdebug，端口设为 9003（与 php.ini 一致）。
- 创建运行配置：Run > Edit Configurations > + > PHP Web Page，选择刚建的 Server，保存。
四 启动调试与验证
- 在代码行号左侧点击设置断点；点击工具栏的 绿色虫子图标（或 Shift+F9）开始监听。
- 触发调试：
- Web 请求：浏览器访问目标 URL；若使用 xdebug.start_with_request=trigger，附加 ?XDEBUG_TRIGGER 参数。
- 命令行脚本：在 PhpStorm 中直接 Run/Debug，或在 CLI 前设置环境变量：export XDEBUG_SESSION=1
- 成功命中后，使用调试工具栏进行 Step Over(F8)、Step Into(F7)、Step Out(Shift+F8)，并在 Variables/Call Stack 面板查看状态。
五 常见问题排查
- 端口冲突：若 9000 被 php-fpm 占用，将 Xdebug 与 PhpStorm 统一改为 9003 或其他端口；同时避免与 IDE 的其他服务端口冲突。
- 断点未生效：
- 核对 php.ini 的 client_host/client_port 与 PhpStorm 一致；远程/容器场景确保 client_host 可达。
- 确认修改的是实际使用的 SAPI 配置（如 FPM 需改 /etc/php/{version}/fpm/php.ini 并重启 php-fpm）。
- 重启服务：sudo systemctl restart apache2 或 sudo systemctl restart php{version}-fpm（及 nginx）。
- 验证配置是否生效：phpinfo() 页面应包含 Xdebug 段落；或 php -i | grep xdebug 查看加载与参数。
