VSCode不运行PHP，所有功能依赖本地php可执行文件是否被正确识别；必须配置php.executablePath绝对路径，否则语法提示、调试、格式化全失效，且需同步设置includePaths、xdebug.mode与launch.json端口。
VSCode 本身不运行 PHP，所有功能都依赖你本地装好的 php 可执行文件是否被正确识别——没配对 php.executablePath，语法提示、调试、格式化全会失效。
终端能跑 php -v，但 VSCode 报 “Command 'php' not found”
这是最常见也最容易被误判的问题。VSCode 图形界面启动时，环境变量（尤其是 PATH）可能和终端不一致，导致它压根找不到你的 php。
- Windows 用户：检查 XAMPP/WAMP/Laragon 的
php.exe路径（如C:\xampp\php\php.exe），确认已加进系统PATH；若仍不行，直接在 VSCode 设置里搜php.executablePath，填绝对路径 - macOS 用户：Homebrew 安装的 PHP（如
php@8.2）默认不软链到/usr/local/bin/php，运行brew link php@8.2或手动填/opt/homebrew/bin/php - Linux 用户：
sudo apt install php-cli通常没问题，但若从源码编译，php可能只在当前用户$PATH，GUI 启动的 VSCode 不继承，必须显式配置php.executablePath - 路径中含空格或中文？别用，重装到干净路径（如
C:\php或/usr/local/php）
Intelephense 提示不准，$this->xxx() 标红但实际能跑
Intelephense 不是魔法，它靠静态分析 + 显式路径扫描来理解代码。漏掉 vendor、app、modules 这类目录，就等于让它“闭着眼写作业”。
- 必须检查设置里的
intelephense.environment.includePaths，把项目中实际存放类/接口/traits 的路径全加进去，例如：["./app", "./vendor", "./modules"] - 如果用了 Composer autoload，确保
composer.json中"autoload"配置正确，然后右键命令面板运行Intelephense: Index workspace - 别开
intelephense.stubs全部——尤其 WordPress、Laravel 等框架 stubs，版本不匹配时会覆盖真实定义，让跳转更混乱 -
php.suggest.basic建议设为false，否则内置补全和 Intelephense 冲突，补全建议重复又不准
Xdebug 3 断点灰色、连不上，Connection refused
Xdebug 3 和 2 的配置项名、默认行为完全不同。照搬旧教程写 launch.json 或 php.ini，90% 概率失败，且错误不报明，只静默拒绝连接。
立即学习“PHP免费学习笔记（深入）”；
- 先验证 Xdebug 是否真加载：运行
php -v，输出里必须有with Xdebug v3.x.x；再运行php --ini找到加载的php.ini，确认zend_extension指向正确的.so或.dll文件 -
php.ini中关键项（Xdebug 3+）：xdebug.mode=debug、xdebug.start_with_request=yes、xdebug.client_host=127.0.0.1、xdebug.client_port=9003（注意不是remote_host或remote_port） - VSCode 的
launch.json必须含pathMappings，哪怕纯本地开发也要写，例如："${workspaceFolder}": "/var/www/html"—— 路径不一致，Xdebug 就找不到对应文件 - Port 必须两端一致：
php.ini里的xdebug.client_port和launch.json中的port都得是9003（改过就得同步）
保存自动格式化后代码反而变乱
VSCode 的 PHP 格式化不干活，它只是调外部工具。混用 phpcbf 和 php-cs-fixer，规则打架，结果就是越修越歪。
- 统一用
php-cs-fixer：全局安装composer global require friendsofphp/php-cs-fixer，然后在 VSCode 设置里填php.format.executablePath为它的绝对路径（如/home/xxx/.composer/vendor/bin/php-cs-fixer） - 关掉
php.suggest.basic，避免和格式化插件冲突；开启editor.formatOnSave，并为[php]设置默认 formatter - 别忽略项目根目录下的
.php-cs-fixer.php配置文件——没它，php-cs-fixer默认只做基础修复，缩进、空行、strict_types 全不会处理 - 如果用 Docker 或远程服务器，
php-cs-fixer必须在目标环境里运行，本地路径映射错会导致格式化失败或路径错误
真正卡住人的从来不是“装什么插件”，而是 php.executablePath 填错、includePaths 漏目录、xdebug.mode 和 launch.json 的 port 不对齐——这些地方一错，整个链条就断了，且错误现象模糊，容易反复折腾。
