PHP Windows调试核心是正确配置php.exe调用及Xdebug扩展：需匹配TS/NTS版本，正确放置DLL并配置php.ini启用xdebug.mode=debug、client_host/port等，注意CLI与Web使用不同php.ini，防火墙可能拦截9003端口。
PHP 在 Windows 下调试，核心是让 php.exe 能被 IDE 或命令行正确调用，并加载调试扩展（如 xdebug 或 zend_extension）。不配对扩展或路径写错，php -v 就看不到 xdebug，IDE 断点直接失效。
确认 PHP 是线程安全版（TS）还是非线程安全版（NTS）
Windows 下 PHP 二进制包分 TS/NTS 两种，Xdebug 扩展必须严格匹配。用命令行执行：
php -i | findstr "Thread Safety"
输出 enabled 表示是 TS 版，disabled 表示是 NTS 版。下载 Xdebug 时务必选对应版本，否则 php.ini 加载会静默失败 —— php -m 不显示 xdebug，php --ini 显示配置已加载，但就是不工作。
- 从 xdebug.org/download 下载对应 PHP 版本、TS/NTS 类型、架构（x64/x86）的
php_xdebug-*.dll - 把 DLL 放进
php/ext/目录（不是ext子目录下再套一层） - 在
php.ini末尾加（注意路径用正斜杠或双反斜杠）：zend_extension="C:/php/ext/php_xdebug-3.3.1-8.2-ts-vs16-x86_64.dll"
配置 xdebug 启用远程调试（vscode / phpstorm 均适用）
Xdebug 3 默认关闭远程调试，仅启用 profiling 或 tracing 不等于能断点。必须显式开启并指定通信方式。在 php.ini 中添加：
立即学习“PHP免费学习笔记（深入）”；
[XDebug] xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.log="C:/tmp/xdebug.log"
关键点：
-
xdebug.mode=debug是必须项，Xdebug 3 不再支持xdebug.remote_enable=1 -
xdebug.start_with_request=yes表示每次请求都尝试连接 IDE，适合 CLI 和 Web 场景；若只想手动触发，改用trigger_value+ 浏览器插件 - 端口默认是
9003（不是旧版的9000），VS Code 的launch.json和 PHPStorm 的 Debug 配置必须同步改 -
xdebug.log路径要确保目录存在且有写权限，出问题时第一手线索就在这里
CLI 脚本调试时常见失败原因
在命令行运行 php script.php 却无法停在断点，大概率是 CLI 使用了和 Web 不同的 php.ini。执行以下命令确认：
php --ini
php -r "echo ini_get('extension_dir');"
你会发现 CLI 的配置文件路径常是 C:\php\php.ini，而 Apache 或 Nginx 可能读的是 C:\php\php-apache.ini。Xdebug 配置必须出现在 CLI 实际加载的那个 php.ini 里。
- 用
php --ini确认 CLI 加载的是哪个文件，别只改了 Apache 对应的 ini - 检查
extension_dir是否指向正确的ext/目录（路径末尾不能有多余斜杠） - 如果用 Composer 安装的依赖含
phpunit或symfony/console，它们可能自带内置服务器，此时需额外传参启用调试，例如：php -dxdebug.mode=debug -dxdebug.start_with_request=yes vendor/bin/phpunit
浏览器中触发 Xdebug 的几种方式
Web 请求不触发断点？不是代码问题，而是没发带调试参数的请求。有三类可靠方式：
- URL 加参数：
http://localhost/test.php?XDEBUG_SESSION_START=1（前提是xdebug.start_with_request=trigger） - 浏览器安装 Xdebug Helper 插件（Chrome/Firefox），点击图标启用后自动加
XDEBUG_SESSION_STARTcookie - 用 curl 手动发带 header 的请求：
curl -H "Cookie: XDEBUG_SESSION=PHPSTORM" http://localhost/test.php
（注意 cookie 值要和 IDE 设置的 key 一致）
最易忽略的一点：Windows 防火墙默认阻止入站连接，xdebug.client_host=127.0.0.1 虽然走本地回环，但某些企业版防火墙策略仍会拦截 9003 端口 —— 临时关闭防火墙或添加入站规则，比反复检查配置更有效。
