VS Code调试PHP失败主因是php.executablePath未配置、Xdebug版本与参数不匹配（如误用xdebug.remote_enable）、launch.json缺少pathMappings；需确保xdebug.mode=debug、client_port与port一致，并严格映射DocumentRoot路径。
VS Code 本身不运行 PHP，装插件只是第一步；断点不生效、跳转找不到类、格式化乱码，90% 是因为 php.executablePath 没配对、Xdebug 版本和配置项不匹配，或 launch.json 缺少 pathMappings。
PHP Intelephense 跳转失效、__construct 标红怎么办
Intelephense 不是“装完就灵”的智能引擎，它靠静态扫描理解项目结构。一旦 vendor 目录没被纳入索引、autoload 规则没识别，就会漏掉类方法甚至基础魔术方法。
- 检查
intelephense.environment.includePaths设置，必须显式加入vendor、app、modules等核心路径，否则只扫当前打开文件夹 - 确认
composer.json中"autoload"和"autoload-dev"配置正确，然后右键命令面板运行Intelephense: Index workspace - 禁用
intelephense.stubs下所有第三方框架 stub（如 laravel-stubs），它们版本不匹配时会覆盖真实定义，反而让跳转更不准 - 别依赖 VS Code 自带的 “PHP Language Features”，它和 Intelephense 冲突，建议直接禁用
PHP Debug 断点灰色、Connection refused 怎么排查
断点不触发不是 VS Code 的锅，而是 Xdebug 3 和 php-debug 插件之间协议没对齐，或者两端监听地址/端口根本没打通。
- 先在终端执行
php -v，输出里必须有with Xdebug v3.x.x，没有说明zend_extension路径错了或扩展文件名不匹配（Linux 是xdebug.so，Windows 是php_xdebug.dll） - 确认
php.ini中启用的是 Xdebug 3 风格配置：xdebug.mode=debug、xdebug.start_with_request=yes、xdebug.client_host=127.0.0.1、xdebug.client_port=9003——xdebug.remote_enable这类 v2 参数已废弃，写了也无效 -
launch.json中的port必须和xdebug.client_port完全一致，且必须设置pathMappings，哪怕本地开发也要写："${workspaceFolder}": "/var/www/html"（值取决于你 Web 服务器 DocumentRoot） - 如果用 Docker 或远程环境，
xdebug.client_host不能写127.0.0.1，得填宿主机 IP（如10.0.2.2）
为什么终端能 php -v，但 VS Code 提示 “Command 'php' not found”
VS Code 图形界面启动时，往往不继承 shell 的 PATH（尤其是 macOS/Linux 的 ~/.zshrc），导致它根本找不到你的 php 可执行文件。
立即学习“PHP免费学习笔记（深入）”；
- 最稳解法：进 VS Code 设置搜
php.executablePath，手动填绝对路径，比如/opt/homebrew/bin/php（macOS Homebrew）、C:\php\php.exe（Windows）或/usr/bin/php（Ubuntu） - Windows 用户注意：安装 PHP 时若没勾选「Add PHP to PATH」，或用了 Laragon/XAMPP 但没把对应
php.exe目录加进系统环境变量，VS Code 就永远找不到 - macOS 用户常见坑：
which php返回/opt/homebrew/bin/php，但 GUI 启动的 VS Code 默认不读~/.zshrc；临时可从终端执行code --no-sandbox启动，长期仍推荐手动填路径
保存自动格式化后代码全乱了
VS Code 的 PHP 格式化功能本身不干活，它只是调外部工具。如果同时装了 php-cs-fixer 和 phpcbf，又没统一指定格式化程序，结果就是规则打架、缩进错位、括号风格混乱。
- 统一用
php-cs-fixer：全局安装composer global require friendsofphp/php-cs-fixer - VS Code 设置中关闭内置建议：
php.suggest.basic设为false，避免和插件冲突 - 开启格式化：
php.format.enable设为true，并设php.format.executablePath为你的php-cs-fixer全路径（如~/.composer/vendor/bin/php-cs-fixer） - 别忽略项目根目录下的
.php-cs-fixer.php配置文件——没它，php-cs-fixer默认只做最基础修复，不会处理空格、括号风格等细节
真正卡住人的地方，从来不是“怎么装插件”，而是 php.ini 里那一行 xdebug.mode=debug 是否生效、launch.json 中 pathMappings 的路径是否和 Web 服务器实际 DocumentRoot 严格对应、以及 VS Code 是否真的读到了你亲手写的那个 php.executablePath —— 这三处任何一个字符出错，调试就彻底静音。
