xdebug.mode=debug是PHP 8.3启用断点调试的唯一必需配置项，旧参数如xdebug.remote_enable已彻底移除；若未设此值或混用废弃参数，断点将静默失效。
xdebug.mode=debug 是 PHP 8.3 下启用断点调试的唯一必需配置项，其他参数不设或设错都可能让断点“静默失效”。
PHP 8.3 必须用 xdebug.mode，不是 xdebug.remote_enable
xdebug.mode，不是 xdebug.remote_enable
PHP 8.3 默认禁用所有 Xdebug 调试能力，旧版配置如 xdebug.remote_enable=1、xdebug.remote_host 已被完全移除，继续保留会触发警告甚至报错。
-
xdebug.mode是 Xdebug 3+ 的统一开关，可组合多个模式：xdebug.mode=debug（断点调试）xdebug.mode=develop,debug（开发+断点，含增强错误提示）xdebug.mode=profile（性能分析） - 若只写
xdebug.mode=debug，但没配xdebug.start_with_request=yes，断点不会自动触发——浏览器访问时需手动加?XDEBUG_SESSION_START=1或用 Xdebug Helper 插件激活。 -
xdebug.client_host和xdebug.client_port必须与 IDE 监听地址/端口严格一致；Windows + WSL 或 Docker 环境下常见填host.docker.internal或10.0.2.2，而非127.0.0.1。
DDEV 用户直接加 webimage_extra_packages: [php8.3-xdebug]
webimage_extra_packages: [php8.3-xdebug]
DDEV v1.22.5+ 对 PHP 8.3 原生支持 Xdebug，无需手动编译或改 php.ini：
- 编辑项目根目录下的
.ddev/config.yaml，加入：webimage_extra_packages: [php8.3-xdebug]
- 运行
ddev restart，DDEV 自动注入预编译好的 Xdebug 扩展并启用xdebug.mode=debug。 - 不要额外在
php.ini里重复写zend_extension或xdebug.*配置——DDEV 容器内已有默认合理值，手动覆盖反而容易破坏路径或端口匹配。 - 验证方式：运行
ddev exec php -v应看到 “with Xdebug v3.4.x”；再跑ddev exec php -i | grep xdebug.mode确认输出为xdebug.mode => debug。
Windows + PhpStorm 路径映射失败？90% 是 path mapping 拼错了
path mapping 拼错了断点命中但变量为空、跳转到空白文件、控制台报 Cannot find a local copy of the file on server E:\www\public\index.php ——这是 Windows 下最典型的路径映射断裂。
立即学习“PHP免费学习笔记（深入）”；
- PhpStorm 的
PHP Server配置中，“Absolute path on the server” 必须和 Apache/Nginx 实际 DocumentRoot 完全一致，且使用正斜杠：E:/www/wwwroot/php/thinkphp/shop_order_rule_design/public。 - “Project root” 对应本地项目路径，也必须是正斜杠，且不能多一层或少一层；例如本地路径是
E:\www\wwwroot\php\thinkphp\shop_order_rule_design，就填E:/www/wwwroot/php/thinkphp/shop_order_rule_design。 - 如果用了虚拟主机（如
loc.rule.com），PhpStorm 的 Server 名称必须和浏览器访问的域名一致（即填loc.rule.com），否则路径映射逻辑不触发。 - 切忌把整个
E:\www映射成/：这会导致 IDE 把E:\www\public\index.php错误解析为/public/index.php，而实际请求路径是/index.php，映射失准。
Xdebug 在 PHP 8.3 下已彻底转向声明式配置，xdebug.mode 是总闸，其余参数都是它的“配件”。最容易忽略的是：断点是否真正被 Xdebug 捕获，不取决于 IDE 是否监听，而取决于每次 HTTP 请求是否携带有效调试会话标识，以及路径映射能否在毫秒级完成符号解析。
