PhpStorm默认不索引外部路径源码，需手动添加至Include Path并确保命名空间结构匹配，否则require后仍无补全、跳转或类型推导。
PhpStorm 默认只索引项目根目录下的文件，外部路径的 PHP 源码（比如放在 /opt/mylib 或 ~/shared/php-utils）不会自动识别——这不是 bug，是设计使然。要让这些文件参与补全、跳转和类型推导，必须显式告诉 PhpStorm “这些代码也是项目的一部分”。
为什么 include 或 require 了还是没提示？
因为 PhpStorm 的代码分析不依赖运行时包含逻辑，它靠的是静态索引 + 命名空间映射。即使你写了 require '/opt/mylib/Helper.php';，只要该路径没被加入 Include Path，IDE 就不会解析里面的类、方法或命名空间。
- 常见现象：Ctrl/Cmd + 点击类名无响应，
use MyLib\Utils;报红，自动补全列表里没有该库的任何符号 - 根本原因：PHP 解释器只知道怎么执行，但 PhpStorm 的索引引擎根本“看不见”那个目录
- 注意：把文件复制进项目再
require是临时解法，但会破坏复用性、增加维护成本，且无法共享同一份源码的多项目更新
手动添加外部目录到 Include Path
这是最直接、最可控的方式，适用于 Git 子模块、本地开发版 SDK、或公司内部未发布到 Packagist 的私有库。
- 打开
File → Settings → PHP → Include Path（macOS 是PhpStorm → Preferences） - 点击右侧
+，选择Add Path，然后浏览并选中外部目录的**根路径**（例如/home/user/my-shared-lib，不是里面的src/子目录） - 确保该目录下有符合 PSR-4 规范的命名空间结构（如
/src/MyLib/Utils.php对应namespace MyLib;），否则类无法按命名空间解析 - 添加后点
OK，等待右下角提示 “Indexing finished” —— 这步不能跳过，否则补全无效
用 External Libraries 节点做项目级绑定
适合临时调试或单个项目强依赖某外部源码，不希望全局污染其他项目。
立即学习“PHP免费学习笔记（深入）”；
- 在项目视图中，右键点击
External Libraries（位于项目树底部），选择Configure PHP Include Path - 点击
+→Add Path，选中你的外部目录（同上，必须是命名空间根） - 这个设置只保存在当前项目的
.idea/目录下，换项目不会生效 - 如果外部库用了
composer.json但又不在项目内，别试图复制vendor/；直接加源码目录更可靠——vendor/里的 autoloader 是为运行时服务的，对 IDE 索引帮助很小
遇到跳转失败或补全缺失时优先检查什么
这类问题 80% 出在路径层级或索引状态，而不是配置本身。
- 确认添加的是「源码根目录」：比如库代码在
/opt/mylib/src/MyLib/，那应该添加/opt/mylib/src，而不是/opt/mylib/src/MyLib - 检查文件是否被标记为 Plain Text：右键文件 →
Override File Type → PHP，否则 PhpStorm 完全忽略其语法结构 - 强制重建索引：
File → Invalidate Caches and Restart → Invalidate and Restart，尤其在添加路径后没立刻生效时必做 - 避免符号冲突：如果外部库和项目里有同名命名空间（比如都叫
App\），IDE 可能混淆，建议统一用带 vendor 前缀的命名空间（如acme/utils）
真正麻烦的不是加路径，而是加完之后发现命名空间对不上、use 语句报错、或者跳转进了一个空 stub 文件——这时候得回头核对源码里的 namespace 声明和目录结构是否严格匹配，少一个子目录层级都会断掉整个链路。
