vscode 调试连不上 xdebug，主因是配置位置错误、路径映射不匹配、cli 与 web 配置混淆、opcache.preload 干扰；需确保 xdebug.mode=debug、client_host/port 正确、pathmappings 精确对应、cli php.ini 启用扩展且无 preload。
php.ini 里 xdebug 配置项写错位置，vscode 就连不上
VSCode 调试连不上，90% 是因为 xdebug.mode、xdebug.client_host 这类配置没放在 PHP 的主配置段，或者被其他 ini 文件覆盖了。
PHP 8.5 默认启用 xdebug.mode=debug，但必须显式指定客户端地址和端口；如果用的是 Docker 或 WSL，xdebug.client_host 不能写 127.0.0.1，得填宿主机真实 IP（比如 macOS 是 host.docker.internal，Windows WSL 是 172.26.128.1）。
-
xdebug.mode必须设为debug（不是develop或空值） -
xdebug.client_port要和 VSCodelaunch.json里的port一致，默认是9003 - 确认
xdebug.start_with_request设为trigger或yes，否则要手动加?XDEBUG_SESSION_START=1 - 运行
php --ini查看实际加载的 ini 文件路径，别在错误的文件里改配置
launch.json 的 pathMappings 对不上，断点永远不命中
VSCode 找不到 PHP 文件对应关系，本质是容器/远程路径和本地路径没映射对。PHP 8.5 + Xdebug 3.3+ 对路径校验更严格，大小写、斜杠方向、末尾是否带 / 全都影响匹配。
常见现象：断点显示为空心圆（未绑定），控制台输出类似 Could not connect to debugging client 或静默失败。
立即学习“PHP免费学习笔记（深入）”；
- 本地项目路径（VSCode 打开的文件夹）必须完整出现在
pathMappings的 value 里，比如"${workspaceFolder}": "/var/www/html" - 如果用 Docker，value 是容器内路径，不是宿主机路径；用 WSL 则注意 Windows 路径转 Linux 格式（
C:\project→/mnt/c/project） - 不要用
~/或环境变量，VSCode 不展开；${workspaceFolder}是唯一安全的变量 - 路径末尾统一不加
/，避免匹配失败
php -v 显示 xdebug，但 phpinfo() 里没有，说明 CLI 和 Web SAPI 加载了不同配置
VSCode 调试走的是 CLI 模式（即使你配的是 Apache/Nginx），所以 php -v 看到 xdebug ≠ Web 请求能调试。必须确认 CLI 的 php.ini 确实启用了 xdebug。
典型错误：只在 /etc/php/8.5/apache2/php.ini 里配了 xdebug，但没动 /etc/php/8.5/cli/php.ini —— VSCode 启动的调试器用的是 CLI 版本。
- 执行
php -i | grep "Loaded Configuration File"，确认 CLI 加载的是哪个 ini - 检查该 ini 文件里是否有
zend_extension=xdebug.so，且没被;zend_extension=注释掉 - Linux 下扩展路径通常是
/usr/lib/php/20230831/xdebug.so（版本号随 PHP 编译版本变），别硬写死 - Mac M-series 用户注意：Homebrew 安装的 PHP 8.5，xdebug.so 路径可能含
arm64，路径不对会静默失败
PHP 8.5 的 opcache.preload 导致 xdebug 断点失效
启用 opcache.preload 后，预加载的文件在 PHP 启动时就被编译进内存，Xdebug 无法对其动态注入断点逻辑 —— 即使文件路径映射正确，断点也永远不会触发。
这不是 bug，是设计限制：preload 文件绕过常规文件加载流程，Xdebug 没机会 hook。
- 开发阶段直接注释掉
opcache.preload行，或设为"" - 不要试图用
xdebug.mode=debug,profile混合模式绕过，preload 会同时禁用所有 Xdebug 功能 - 如果必须保留 preload（如本地模拟生产），把要调试的类/文件从 preload 列表里移出
- 重启 PHP-FPM 或 Apache 后，务必用
php -r "echo opcache_get_status()['preload_statistics']['memory_consumption'];"确认 preload 已停用
