Xdebug断点不触发主因是xdebug.mode未设为debug或client_port与IDE监听端口不一致；需删除所有remote_参数，确保xdebug.mode=debug、client_port=9003、start_with_request合理设置，并验证URL触发或插件启用。
Xdebug断点不触发，90%是因为 xdebug.mode 没设成 debug，或 client_port 与 IDE 监听端口不一致——不是版本问题，更不是重启能解决的玄学。
确认 xdebug.mode=debug 且无 remote_ 参数残留
Xdebug 3.x 完全废弃 xdebug.remote_enable、xdebug.remote_host 等所有带 remote_ 前缀的配置。混用会导致 xdebug_info() 显示已加载，但断点静默失效。
- 执行
php --ri xdebug，检查输出中xdebug.mode的值是否包含debug（如debug,develop或纯debug） - 打开实际生效的
php.ini（用php --ini确认路径），删掉所有含remote_的行 - 只保留这几行核心配置（本地直连场景）：
zend_extension=xdebug.so<br>xdebug.mode=debug<br>xdebug.start_with_request=trigger<br>xdebug.client_host=127.0.0.1<br>xdebug.client_port=9003<br>xdebug.idekey=PHPSTORM
- Docker 环境下
xdebug.client_host必须设为host.docker.internal，不能写localhost
IDE 必须监听 9003 端口并允许外部连接
PHP 进程主动反向连接 IDE，不是 IDE 主动连 PHP。端口不匹配或未开启监听，xdebug.log 里会出现 Connection to '127.0.0.1:9003' failed。
- PhpStorm：进入
Settings > PHP > Debug，确认Debug port是9003，且勾选Can accept external connections - VS Code：检查
.vscode/launch.json中"port": 9003，启动调试会话时点绿色 ▶（不是直接按 F5） - 命令行验证端口是否被监听：
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows） - Windows Defender 或其他杀毒软件可能拦截 9003 端口，需手动放行
浏览器请求必须携带 XDEBUG_SESSION_START 参数
Xdebug 不会自动监听所有请求。没有触发标识，它根本不会尝试连接 IDE，断点自然不生效。
立即学习“PHP免费学习笔记（深入）”；
- 最可靠方式：安装官方 Xdebug Helper 浏览器插件（Chrome/Firefox），点击虫子图标选择
Debug，它会自动在 URL 后加?XDEBUG_SESSION_START=PHPSTORM并设置 Cookie - 手动测试可用：
http://localhost/test.php?XDEBUG_SESSION_START=PHPSTORM - 确保插件里设置的 IDE Key 和
php.ini中的xdebug.idekey一致（默认都是PHPSTORM） -
xdebug.idekey已被弃用，真正起效的是 URL 参数或 Cookie 中的XDEBUG_SESSION_START值
PHP-FPM 场景下注意配置覆盖问题
Web SAPI（如 Apache/mod_php）和 CLI 的 php.ini 常不同，而 PHP-FPM 更进一步：其 pool.d/www.conf 可能通过 php_admin_value[xdebug.mode] 强制覆盖全局配置，导致你改了 php.ini 却完全无效。
- 检查
/etc/php/*/fpm/pool.d/www.conf（路径依系统而异），搜索xdebug.mode或php_admin_value - 若存在类似
php_admin_value[xdebug.mode] = off，要么注释掉，要么改为debug - 改完后必须重启
php-fpm服务，而非仅 reload - CLI 调试时，
php -dxdebug.start_with_request=yes script.php不稳定，推荐用环境变量：XDEBUG_CONFIG="idekey=PHPSTORM" php script.php
路径映射（path mappings）容易被忽略：Docker、远程服务器或 WSL 下，容器内 /var/www/html 和你本地项目路径不一致时，断点会“命中但不暂停”。必须在 IDE 的 Servers 设置里启用 Use path mappings 并正确配对。
