Xdebug 是 PHP 调试核心扩展，需匹配 PHP 版本架构安装，并在 php.ini 中配置 xdebug.mode=debug、client_host、client_port 等参数，再于 IDE（如 VS Code）中启用监听并触发调试会话。
Xdebug 是 PHP 最常用的调试扩展，能帮你单步执行、查看变量、分析性能。关键不是装上就完事，而是配对 IDE（如 PHPStorm、VS Code）才能真正用起来。
安装 Xdebug 扩展
先确认 PHP 版本和架构（32/64 位、线程安全 TS/非线程安全 NTS），再下载对应 xdebug.dll（Windows）或 xdebug.so（Linux/macOS）。推荐用官方安装向导：xdebug.org/wizard，粘贴 phpinfo() 输出，它会给出精准安装步骤。
- 把扩展文件放进
php/ext/目录 - 在
php.ini中添加：zend_extension=xdebug.so ; Linux/macOS<br>; 或 zend_extension=php_xdebug.dll ; Windows
- 重启 Web 服务（Apache/Nginx）或 PHP-FPM
- 运行
php -v或刷新phpinfo()，看到 Xdebug 行说明加载成功
配置基础调试参数
仅启用扩展还不够，得告诉 Xdebug 怎么跟你的编辑器通信。在 php.ini 中追加以下常用配置（PHP 8.0+ 推荐用 xdebug.mode=debug）：
-
xdebug.mode = debug —— 启用调试模式（代替旧版
xdebug.remote_enable=1） -
xdebug.start_with_request = trigger —— 只在带
XDEBUG_SESSION_START=1参数或 Cookie 时启动（更安全） - xdebug.client_host = 127.0.0.1 —— 指定 IDE 监听的 IP（Docker 环境可能需设为宿主机 IP）
- xdebug.client_port = 9003 —— 默认端口，要和 IDE 设置一致（新版 Xdebug 用 9003，不是旧版 9000）
- xdebug.log = /tmp/xdebug.log（可选）—— 开启日志，排错时很有用
在 IDE 中设置断点并启动监听
以 VS Code 为例：安装 PHP Debug 插件（由 Felix Becker 提供），打开项目，在任意 PHP 文件左侧行号边点击设断点（红点）。然后点击左下角 ▶️ 图标，选择 “Listen for Xdebug”。这时 IDE 就在 9003 端口等待连接。
立即学习“PHP免费学习笔记（深入）”；
- 浏览器访问目标 URL，并手动加上
?XDEBUG_SESSION_START=1（例如http://localhost/index.php?XDEBUG_SESSION_START=1） - 或安装浏览器插件（如 Xdebug Helper），一键开启调试会话（自动加 Cookie）
- 请求发出后，VS Code 会自动停在断点，你可以查看变量值、调用栈、逐行执行（F10）、步入函数（F11）、跳出（Shift+F11）
常见问题快速排查
连不上？别急着重装，先看这几处：
- 运行
php --ini确认修改的是正在使用的php.ini - 检查
phpinfo()页面中 Xdebug 配置项是否生效，特别是xdebug.mode和xdebug.client_host - 防火墙是否拦截了 9003 端口（尤其是 Windows Defender 或 macOS 防火墙）
- Docker 环境下，
client_host不能写127.0.0.1，得填宿主机网关（如172.17.0.1）或用host.docker.internal（Docker Desktop 支持） - PHPStorm 用户注意：默认监听端口是 9003，但旧项目模板可能还设成 9000，需在 Preferences → PHP → Debug → Xdebug 中核对
配通一次，后续调试就顺了。重点是版本匹配、端口统一、触发方式明确。不复杂但容易忽略细节。
