linux环境下phpstorm如何配置xdebug

Linux下 PhpStorm 配置 Xdebug 实操指南

一 环境准备与版本确认

• 确认 PHP 版本与 SAPI：运行 php -v 与 php -m 查看版本与已加载扩展；通过 php --ini 定位 CLI 使用的 php.ini。Web 环境请在站点根目录放置 phpinfo.php 并访问，从页面中查看 Loaded Configuration File 与 Xdebug 段。注意：CLI 与 Apache/Nginx+PHP-FPM 常使用不同的 php.ini，修改错文件会导致调试无效。若使用包管理器安装扩展，常见命令为：sudo apt-get install php-xdebug 或 sudo apt-get install php7.x-xdebug（将 x 替换为你的 PHP 主次版本）。

二 安装与配置 Xdebug

• 安装方式（三选一）
  • 发行版包管理器：sudo apt-get install php-xdebug（或 php7.x-xdebug）。安装后扩展通常自动启用，仍需在对应 php.ini 中确认配置。
  • PECL：pecl install xdebug（需已安装 php-dev/phpize 与编译工具），安装完成后在 php.ini 中以 zend_extension=xdebug.so 加载。
  • 源码编译：下载匹配你 PHP 版本的 Xdebug，解压后执行 phpize → ./configure --enable-xdebug → make && make install，在 php.ini 中以 zend_extension=/path/to/xdebug.so 加载。
• php.ini 关键配置（按 Xdebug 版本区分）
  • Xdebug 3.x（推荐）

    [xdebug]
    zend_extension=xdebug.so
    xdebug.mode=debug
    xdebug.client_host=127.0.0.1
    xdebug.client_port=9003
    xdebug.start_with_request=yes    ; 或 trigger 按需触发
    ; 可选：开启日志便于排错
    ; xdebug.log=/tmp/xdebug.log
    

  • Xdebug 2.x（旧版）

    [xdebug]
    zend_extension=xdebug.so
    xdebug.remote_enable=1
    xdebug.remote_host=127.0.0.1
    xdebug.remote_port=9000
    xdebug.remote_handler=dbgp
    xdebug.remote_autostart=1
    ; 或按需触发
    ; xdebug.remote_autostart=0
    ; xdebug.idekey=PHPSTORM
    

  • 重要差异
    • 3.x 使用 xdebug.mode=debug、xdebug.client_host、xdebug.client_port；2.x 使用 remote_enable/remote_host/remote_port 等。
    • 加载扩展请使用 zend_extension，不要写成 extension。
    • 端口默认从 9000 调整为 9003（3.x），如与 php-fpm 冲突请改为未占用端口（如 9001/9003）。

三 PhpStorm 侧配置

• 解释器：File → Settings → PHP → Interpreter，添加本机 PHP 可执行文件（如 /usr/bin/php），确认已识别 Xdebug。
• 调试端口：Settings → PHP → Debug，将 Debug port 设为与 php.ini 一致的 9003（或 9000）。
• 服务器与路径映射：Settings → PHP → Servers → +，填写 Name/Host/Port；勾选 Use path mappings，将本地项目路径映射到服务器（或容器）路径，确保断点能命中。
• DBGp Proxy（可选，多机/容器协作时使用）：Settings → PHP → Debug → DBGp Proxy，配置 IDE key、Host、Port 与团队保持一致。
• 启动监听：点击工具栏电话图标 Start Listening for PHP Debug Connections，图标变绿表示监听中。

四 触发调试与验证

• Web 调试
  • 浏览器方式：安装 Xdebug Helper（Chrome/Firefox），在插件中设置与 php.ini 一致的 IDE key（如使用），访问目标 URL 即可触发；或在 URL 后追加 ?XDEBUG_SESSION_START=1 临时触发。
  • 确保 PhpStorm 处于监听状态，命中断点后可查看变量、堆栈与单步执行。
• CLI 脚本调试
  • 方式一：在 PhpStorm 中 Run → Debug，选择或创建 PHP Script 运行配置直接调试。
  • 方式二：命令行执行脚本前设置环境变量（3.x）：export XDEBUG_SESSION=1，然后运行脚本；确保 PhpStorm 正在监听相同端口。
• 验证要点
  • 执行 php -v 应看到 with Xdebug；php -m | grep xdebug 应能看到 xdebug。
  • 访问 phpinfo.php 应能看到 Xdebug 段与你的配置值（如 xdebug.mode=debug、xdebug.client_port=9003）。
  • 若使用容器/远程主机，确认 client_host 指向运行 PhpStorm 的机器 IP，必要时开放或转发 9003 端口。

五 常见问题与排查

• 修改了错误的 php.ini：CLI 与 Web 常不同，务必用 php --ini 与 phpinfo() 分别确认后再改；否则看似配置正确却不生效。
• 端口冲突或被占用：将 xdebug.client_port/remote_port 与 PhpStorm 统一为 9003（或未被占用的端口），用 lsof -i :9003 检查占用并释放。
• 扩展未以 zend_extension 加载：Xdebug 必须使用 zend_extension=xdebug.so，写成 extension 会导致不生效或告警。
• 版本不匹配：Xdebug 2 与 3 配置项差异大，优先使用 3.x 的新参数；不确定版本时查看 php -v 输出或 phpinfo 的 Xdebug 版本号。
• 防火墙/网络不通：容器、虚拟机、远程服务器场景需保证 client_host 可达且端口开放；必要时使用 SSH 隧道转发 9003。
• 路径映射缺失：Web 项目必须配置 Servers → Use path mappings，否则断点可能不生效。
• 开启日志定位：在 php.ini 增加 xdebug.log=/tmp/xdebug.log，根据日志快速定位握手与连接问题。