在 Linux 上使用 PhpStorm 调试 PHP 代码
一 准备与安装
- 安装并启动 PhpStorm（Linux 版）：从 JetBrains 官网下载安装包，解压后执行安装脚本，例如：chmod +x phpstorm.sh 与 sudo ./phpstorm.sh。首次启动按提示完成配置。
- 安装并验证 PHP：确保系统已安装 PHP，命令行执行 php -v 可查看版本。
- 安装 Xdebug：
- Ubuntu/Debian 系可直接安装包管理器提供的扩展：sudo apt-get install php-xdebug；
- CentOS/RHEL 系可使用 yum/dnf 安装对应版本的 php-xdebug 扩展包。
以上完成 IDE、PHP 与调试器的基础准备。
二 配置 Xdebug
- 确认 Xdebug 已启用：执行 php -m | grep xdebug，能看到 xdebug 即表示加载成功。
- 编辑 PHP 配置（php.ini 或 /etc/php.d/ 下的 xdebug.ini），按 Xdebug 版本写入对应参数：
- Xdebug 2 常用参数（示例）：
- zend_extension=/usr/lib/php/20190902/xdebug.so
- xdebug.remote_enable=1
- xdebug.remote_host=127.0.0.1
- xdebug.remote_port=9001
- xdebug.idekey=PHPSTORM
- xdebug.remote_autostart=0（建议按需启动，避免对所有请求生效）
- Xdebug 3 常用参数（示例）：
- zend_extension=xdebug
- xdebug.mode=debug
- xdebug.client_port=9003
- xdebug.start_with_request=trigger（配合触发参数使用）
- 重启 Web 服务或 PHP-FPM 使配置生效：
- Apache：sudo systemctl restart apache2
- PHP-FPM：sudo systemctl restart php-fpm
以上完成调试器与 PHP 的联动配置。
三 在 PhpStorm 中创建调试运行配置
- 配置 Servers：File → Settings → Languages & Frameworks → PHP → Servers → +，填写 Name、Host（如 localhost 或服务器域名/IP），端口（如 80/443），勾选 Use path mappings，将本地项目路径映射到服务器上的绝对路径（服务器路径务必准确，否则断点无法命中）。
- 新建运行配置：Run → Edit Configurations → + → PHP Web Page（或 PHP Remote Debug）。
- 选择 Server；
- 设置 Start URL（要调试的页面）；
- Debugger 选择 Xdebug；
- 端口与 php.ini 中 xdebug.client_port/remote_port 保持一致（例如 9001/9003）。
- 启动监听：点击工具栏的“电话听筒”图标，开始监听调试连接。
四 开始调试
- Web 页面调试：在浏览器访问目标 URL，并在 URL 后附加触发参数以启动调试会话，例如：http://your-app.local/page.php?XDEBUG_SESSION_START=PHPSTORM；随后 PhpStorm 会捕获连接并停在断点处，可使用变量查看、单步执行、观察表达式等。
- CLI/脚本调试（本地或远程服务器）：
- 本地脚本：在 PhpStorm 中直接对脚本创建运行配置（如 PHP Script），设置断点后点击 Debug 运行；
- 远程服务器脚本：通过 SSH 隧道将服务器上的调试端口（如 9003）转发到本机（例如 ssh -R 9003:localhost:9003 user@server），在 PhpStorm 中监听相同端口并启动调试。
- 触发方式建议：开发环境可用 xdebug.start_with_request=trigger 或设置 xdebug.remote_autostart=1；生产环境不建议长期开启自动调试。
五 常见问题与快速排查
- 端口不通：确认 php.ini 的 client_port/remote_port 与 PhpStorm 运行配置一致，且本机防火墙/云安全组放行该端口；如使用远程服务器，优先用 SSH 隧道转发端口。
- 断点不命中：检查 Servers 的 Path mappings 是否一一对应本地与服务器路径；确认访问的是配置中的 Server 的 Host/Port。
- 版本不匹配：Xdebug 2 与 Xdebug 3 参数差异较大，务必按所用版本写入对应配置项；不确定时先 php -v 与 php -m 确认扩展与版本。
- 无法连接：在 PhpStorm 的 Settings → PHP → Debug 中点击 Validate 校验调试环境；同时查看 Web 服务/PHP-FPM 错误日志与 Xdebug 日志以定位问题。