PhpStorm报错：Laravel仓库返回类型错误，预期User实际返回Eloquent\Model|object

核心原因 #

PhpStorm的静态类型解析默认不支持Laravel Eloquent的动态魔术方法调用逻辑，查询构造器的返回类型没有和User模型做关联，所以会出现运行正常但IDE报类型错误的误报，这类误报也会被默认配置的PHPStan/Code Sniffer识别为警告。

可落地的解决方法 #

• 单处查询临时修复：给查询结果增加显式变量类型注解，PHPStan和PhpStorm都能识别：

/** @var \App\Models\User $user */
$user = User::where('id', $id)->first();

• 全项目静态检查修复：安装Larastan扩展包，它是官方适配的Laravel专用PHPStan扩展，配置后可自动识别所有Eloquent查询对应的模型类型：
  1. 执行安装命令 composer require nunomaduro/larastan --dev
  2. 在phpstan.neon配置文件中引入扩展规则即可
• IDE层面全局修复：安装PhpStorm的Laravel Idea付费插件，安装后无需额外配置即可自动识别所有Eloquent查询、模型关联、Scope方法的返回类型，同时兼容Larastan的解析结果，不会再出现类型误报。
• 自定义查询Scope修复：如果是你自己封装的模型查询方法，给方法增加泛型注解即可：

/**
 * @return \Illuminate\Database\Eloquent\Builder<\App\Models\User>
 */
public function scopeActive($query)
{
    return $query->where('status', 1);
}

• 严谨场景修复：增加类型断言语句，静态分析工具和IDE都会识别后续变量的正确类型，同时运行时也能做校验：

$user = User::find($id);
assert($user instanceof \App\Models\User);

内容的提问来源于stack exchange，提问作者DarkPeTruS