IDE 无法识别自定义关系和查询构建器方法，根本原因是 PHPDoc 声明与 Laravel 运行时行为不一致：@mixin 未置于模型类顶部，或 additional_relation_types 配置未正确写入 config/ide-helper.php 且未重新生成 _ide_helper.php。
IDE 识别不了自定义关系、查询构建器方法，不是插件没装对，而是 PHPDoc 声明没对上 Laravel 的运行时行为。 直接补全失效、Go to Definition 点不动、链式调用断在第一个自定义方法——这些问题几乎都卡在两个地方：@mixin 没写对位置，或 additional_relation_types 配置没生效。
自定义关系类型不提示？检查 additional_relation_types 配置项
IDE Helper 不会自动猜你写的 externalHasMany 是什么类型，必须显式告诉它。
-
additional_relation_types必须写在config/ide-helper.php中，且键名要和模型里实际调用的方法名**完全一致**（大小写敏感） - 值必须是完整类名，比如
\App\Relations\ExternalHasMany::class，不能漏掉::class - 如果关系方法返回的是集合但 IDE 仍提示为单个模型，还要配
additional_relation_return_types，例如：'externalHasMany' => 'many' - 改完配置后必须重新运行：
php artisan ide-helper:generate，否则不会更新_ide_helper.php
自定义查询构建器方法不补全？@mixin 必须写在模型类顶部
哪怕你已经重写了 newEloquentBuilder() 并返回了正确的构建器实例，PhpStorm 依然看不到那些方法——除非用 @mixin 显式声明。
-
@mixin注解必须放在模型类的 PHPDoc 块**最顶部**，紧贴class关键字上方 - 不能写在 trait 里再
use进来，Laravel Idea 和 PhpStorm 当前都不穿透 trait 解析@mixin - 构建器类必须继承
Illuminate\Database\Eloquent\Builder，且所有链式方法返回self（不是static或Builder） - 如果模型用了
newEloquentBuilder()，确保其返回类型与@mixin声明的类一致，否则提示会在query()后就断裂
VSCode 里链式调用提示断掉？Intelephense 需要手动加载生成文件
VSCode 默认不读 _ide_helper.php，Intelephense 必须被明确告知这些辅助文件的存在。
- 运行
php artisan ide-helper:generate和php artisan ide-helper:models -n后，确认_ide_helper.php和_ide_helper_models.php已生成在项目根目录 - 在 VSCode 设置中配置：
intelephense.environment.includePaths包含项目根路径（${workspaceFolder}） - 同时设置：
intelephense.stubsPath指向_ide_helper.php所在目录（通常就是根目录） - 改完设置后必须重启 VSCode 窗口，仅重载窗口不够
最容易被忽略的一点：所有自定义类型提示都依赖「静态声明」与「运行时行为」严格对齐。比如 @mixin 写了 UserQueryBuilder，但 newEloquentBuilder() 实际返回的是 BaseQueryBuilder 子类，或者构建器里某个方法返回了 Collection 而不是 self，提示就会在那个方法处戛然而止——IDE 不会尝试推断，只认你写的字面量。
