VSCode不运行PHP，仅调用系统已安装的php可执行文件；路径未配置或配错会导致所有PHP功能失效。终端能运行php -v但VSCode报“Command 'php' not found”，主因是图形界面启动时不继承shell的PATH，需在设置中手动指定php.executablePath绝对路径，如/opt/homebrew/bin/php或C:\xampp\php\php.exe，并重启VSCode生效。
VSCode 本身不运行 PHP，它只调用你系统里已安装的 php 可执行文件；没装 PHP 或路径配错，所有功能（语法提示、调试、格式化）都会失效，不是插件问题，而是底层依赖缺失。
终端能跑 php -v，但 VSCode 报 “Command 'php' not found”
这是最常被忽略的环境隔离问题：VSCode 图形界面启动时，往往不继承 shell 的 PATH（尤其 macOS/Linux 的 zsh 配置、Windows 的系统 vs 用户变量差异）。别猜，直接验证：
- 在 VSCode 内置终端里运行
which php（macOS/Linux）或where php（Windows），看输出路径是否和你预期一致 - 如果路径正确但插件仍报错，大概率是 VSCode 启动方式导致环境变量未加载——改用命令行启动：
code . - 最稳妥方案：打开设置（
Ctrl+,或Cmd+,），搜php.executablePath，填入绝对路径，例如：/opt/homebrew/bin/php（Apple Silicon Homebrew）、C:\xampp\php\php.exe（Windows） - 路径中避免中文、空格；若必须含空格，用双引号包裹（如
"C:\Program Files\php\php.exe"），但建议重装到无空格路径
php --ini 显示的配置文件和你改的 php.ini 不是一份
本地集成环境（XAMPP/MAMP/WAMP）通常有两套 php.ini：一套给 Apache（在 apache/bin/ 下），一套给 CLI（在 php/ 目录下，可能叫 php.ini-development 或无后缀）。VSCode 的 PHP 插件默认读 CLI 模式配置，你改了 Apache 的那份，CLI 还在用默认配置。
- 运行
php --ini，看输出的 “Loaded Configuration File” 路径，直接编辑它 - Windows 下 MAMP 的 CLI 配置文件通常是
C:\MAMP\bin\php\php8.2.10\php.ini，不是C:\MAMP\conf\php\php.ini - 改完必须重启 VSCode —— Intelephense 等插件会缓存语言服务器状态，不重启可能继续报 “extension not loaded”
断点灰色、hover 显示 “unbound breakpoint”
这不是 VSCode 或 Xdebug 单方面的问题，而是两端路径映射没对齐。即使纯本地开发（没 Docker/Vagrant），只要项目不在 Web 根目录，pathMappings 就必须配。
立即学习“PHP免费学习笔记（深入）”；
- 先确认 Xdebug 已加载：访问
phpinfo()页面，搜索 “xdebug”，看是否显示已启用且版本匹配（Xdebug 3 和 2 的配置项名完全不同） - 检查
php.ini中关键项：xdebug.mode=debug（v3）、xdebug.start_with_request=yes、xdebug.client_port=9003（必须和 VSCodelaunch.json中的port完全一致） -
launch.json中的pathMappings必须显式声明本地路径与服务器路径的对应关系，例如："${workspaceFolder}": "/var/www/html"；如果项目结构是myapp/public/index.php，而 Web 服务器根目录是public，那映射就得写成"${workspaceFolder}/public": "/var/www/html" - 别依赖
${env:HOME}或其他动态变量——Intelephense 和 Xdebug 都无法解析它们，静态路径最稳
保存后代码格式乱掉，或补全失效
根本原因是多个工具在抢控制权：VSCode 内置的 PHP 补全（php.suggest.basic）和 Intelephense 冲突；格式化工具（php-cs-fixer vs phpcbf）混用导致规则打架。
- 关掉内置补全：
php.suggest.basic设为false，否则 Intelephense 的跳转、类型推断会降级 - 统一用
php-cs-fixer：全局安装composer global require friendsofphp/php-cs-fixer，然后在设置中指定php.format.executablePath为它的完整路径（如/home/xxx/.composer/vendor/bin/php-cs-fixer） - 别忽略项目根目录下的
.php-cs-fixer.php配置文件——没它，php-cs-fixer默认只做基础修复，缩进、空格、括号风格全不会生效 - Intelephense 的
intelephense.environment.includePaths必须包含vendor或框架源码路径，否则use类、new实例都跳转失败
真正卡住人的从来不是某个配置项写错，而是 CLI 和 Web 服务器用的不是同一份 php.ini，或者 pathMappings 里漏掉了一层子目录——这种细节在文档里很少强调，但实际调试时，90% 的“连不上”“跳不到”都源于此。
