Ubuntu下使用 PhpStorm 的高效调试技巧
一 基础环境快速配置
- 安装 Xdebug（适配你的 PHP 版本，如 7.4/8.0/8.1/8.2/8.3）：sudo apt-get install php-xdebug。完成后在 PHPStorm 的 File > Settings > PHP > Debug 确认调试端口为 9003。
- 配置 php.ini（或同目录的 xdebug.ini，路径如：/etc/php/{version}/{sapi}/php.ini 或 /etc/php/{version}/mods-available/xdebug.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.idekey=PHPSTORM
注：CLI 与 FPM/Apache 可能分别有各自的 php.ini，需分别配置；保存后重启服务：sudo systemctl restart php{version}-fpm / apache2 / nginx。
- 在 PhpStorm 设置 Languages & Frameworks > PHP > Servers：新增服务器，Host 填 localhost，端口 80/443，Debugger 选 Xdebug；在 Run > Edit Configurations 新建 PHP Web Page，选择刚建 Server，Start URL 填入口页面。
- 触发调试：在代码行左侧点下断点，点击工具栏虫子图标启动；浏览器访问页面即可命中断点。
二 本地与远程调试的实用技巧
- 一键启动监听：使用工具栏电话图标或 Run > Start Listening for PHP Debug Connections，保持监听，命中即停。
- 浏览器一键调试：安装 Xdebug Helper（Chrome/Firefox），在插件选项中将 IDE key 设为 PHPSTORM 并启用；访问页面即可自动连接 PhpStorm。
- 手动触发会话：在 URL 后追加参数 ?XDEBUG_SESSION_START=PHPSTORM，或在请求中携带 Cookie XDEBUG_SESSION=PHPSTORM，即可强制进入调试。
- 命令行脚本调试：在终端执行前设置环境变量（适配 Xdebug 3）：
export XDEBUG_SESSION=PHPSTORM
php your_script.php
然后在 PhpStorm 中对脚本设置断点并开始监听。
- API/接口调试：在 Postman 等工具中新建请求，添加 Cookie XDEBUG_SESSION=PHPSTORM，发送请求即可命中断点。
三 远程服务器与容器场景
- 本机运行服务、代码在虚拟机/容器：将 xdebug.client_host 设为 宿主机在虚拟机/容器网络中的可达 IP（如 192.168.x.x 或 Docker 的 host.docker.internal），保持 client_port=9003 与 PhpStorm 一致；在 PhpStorm 的 Servers 配置中把 Host 设为服务器域名/IP。
- 远程服务器直连本机：将 xdebug.client_host 设为你的 公网/内网 IP，并确保网络与防火墙放行 9003；PhpStorm 端保持监听即可。
- 远程解释器与路径映射：在 File > Settings > PHP > Remote Interpreters 添加远程 PHP 解释器；在 Run/Debug Configurations > PHP Web Page > Server 中配置 Absolute path on the server 与本地项目路径的映射，保证断点能正确对齐。
四 调试效率提升与常见问题
- 常用控制：
- Step Over（F8）：执行下一行，不进入函数内部。
- Step Into（F7）：进入函数内部。
- Force Step Into：强制进入，跳过构造/前置方法直达函数首行。
- Step Out（Shift+F8）：跳出当前函数。
- Run to Cursor：运行到光标所在行。
- 条件与日志断点：在断点上右键设置条件（如仅当 $id === 123 时中断）或命中日志，减少频繁中断。
- 变量与堆栈：在 Variables/ Watches 面板查看与监视表达式；在 Frames 面板快速跳转调用栈。
- 常见问题速排：
- 端口占用：检查 9003 是否被其他进程占用（如 php-fpm 默认 9000 冲突），必要时调整 xdebug.client_port 与 PhpStorm 一致。
- 命中不到断点：确认 xdebug.mode=debug、client_host/client_port 正确，服务器与 PhpStorm 监听已开启，且 Servers 的 Host/端口映射无误。
- 仅 CLI 生效：检查是否只改了 CLI 的 php.ini，未同步修改 FPM/Apache 的配置并重启对应服务。
- 远程连不通：核对 client_host 是否为对端可达 IP，云服务器需放行 9003 安全组/防火墙规则。