Intelephense 扩展未正确配置或索引异常会导致 PHP 智能补全失效；需依次启用扩展、配置 PHP 路径、重建索引、设置 stubs 并禁用冲突语言服务器。
如果您在使用 vscode 编写 php 项目时发现函数名、类名或变量名无法自动提示，或者跳转定义失效，则可能是 intelephense 扩展未正确配置或索引异常。以下是恢复智能补全功能的具体操作步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、检查并启用 Intelephense 扩展
Intelephense 必须处于启用状态且为当前工作区的活跃语言服务器，否则 PHP 文件将回退至基础文本模式，失去语义分析能力。
1、点击左侧活动栏的扩展图标（方块拼图形状）。
2、在搜索框中输入 Intelephense，确认已安装由 Ben Mewburn 发布的官方版本。
立即学习“PHP免费学习笔记（深入）”；
3、若右侧显示“禁用”，点击该按钮切换为“启用”；若显示“已启用”，继续下一步。
二、验证 PHP 路径配置
Intelephense 需要调用本地 PHP 可执行文件以解析语法和类型信息，路径错误会导致符号解析失败，进而中断补全逻辑。
1、按下 Cmd + , 打开设置界面。
2、在搜索框中输入 intelephense.executablePath。
3、点击“在 settings.json 中编辑”，在花括号内添加键值对："intelephense.executablePath": "/usr/bin/php"（如使用 Homebrew 安装 PHP，请替换为 /opt/homebrew/bin/php）。
三、强制重建符号索引
当项目结构变更或新增 composer 包后，Intelephense 的缓存索引可能滞后，导致新类无法被识别，需手动触发全量重新索引。
1、按下 Cmd + Shift + P 打开命令面板。
2、输入 Intelephense: Index workspace 并回车。
3、状态栏右下角出现蓝色进度条，待其消失且提示 Indexing completed 后，重启 VSCode 窗口。
四、配置 workspace-level intelephense.stubs
默认情况下 Intelephense 仅加载核心 PHP 存根，若项目依赖特定扩展（如 gd、mbstring、redis），需显式声明，否则对应函数不会出现在补全列表中。
1、在项目根目录创建 .vscode/settings.json 文件（如不存在）。
2、写入以下内容：
"intelephense.stubs": ["php", "gd", "mbstring", "redis", "curl"]
3、保存文件，等待右下角弹出 Configuration updated 提示。
五、禁用冲突的语言服务器
PHP Intelephense 与 PHP Language Server（phpserver）不能共存，后者会抢占语言功能端口，造成补全延迟或完全失效。
1、打开命令面板（Cmd + Shift + P）。
2、输入 Preferences: Configure Language Specific Settings... 并回车。
3、选择 PHP，在打开的 settings.json 片段中添加：
"php.suggest.basic": false
