“Interface not found”错误表示PHP在解析阶段未加载接口定义，常见原因包括：接口文件未引入、命名空间错误、接口名拼写或大小写错误、Composer自动加载未覆盖接口路径、内置接口对应扩展未启用（如json）、IDE误补全。
Interface not found 是 PHP 找不到接口定义，不是“没实现”
这个报错和 TypeError: Argument 1 passed to ... must be an instance of XxxInterface 完全不同——它发生在解析阶段，PHP 连接口类名都认不出来，直接中止。常见于以下场景：
- 接口文件没被加载（
require/include漏了，或自动加载失败） - 命名空间写错，比如声明了
namespace AppContracts;，但use AppContractUserRepositoryInterface;少了个s - 接口名拼写错误，如把
JsonSerializable写成JSONSerializable（大小写敏感） - PHP 扩展缺失，典型如
Interface 'JsonSerializable' not found—— 实际是json扩展未启用
验证方式很简单：在报错文件顶部加一行 var_dump(class_exists('YourInterfaceName', false));，返回 false 就确认是加载问题。
Composer 自动加载没覆盖接口文件
很多项目把接口放在 app/Contracts/ 或 src/Interfaces/，但 composer.json 的 "autoload" 没配对。结果就是 IDE 能跳转、PHP 却说“找不到”。
- 检查
composer.json中是否包含对应目录，例如："autoload": { "psr-4": { "App\": "app/", "App\Contracts\": "app/Contracts/" } } - 改完后必须运行
composer dump-autoload，否则修改不生效 - 如果接口在
vendor/下（如 Magento、Hyperf 插件），确认包已正确composer require，且没有被composer install --no-dev意外跳过 - 临时调试可加
require_once __DIR__ . '/path/to/YourInterface.php';快速验证是否路径问题
Laravel / Hyperf 等框架里 interface 文件路径或命名空间错位
框架项目结构严谨，一个字母错就会触发 Interface not found。尤其注意：
立即学习“PHP免费学习笔记（深入）”；
- Laravel 默认不扫描
app/Interfaces/目录，如果你建了这个目录但没在composer.json声明，就必然报错 - Hyperf 3.0+ 强制使用 PSR-4，接口若放在
app/Model/Interfaces/，就必须匹配命名空间AppModelInterfaces，不能漏掉中间的Interfaces - Mageento 2 报
VertexTaxModelFlexfieldProcessorInvoiceFlexFieldProcessorInterface not found，往往是use语句漏写，或模块未启用（bin/magento module:enable Vertex_Tax） - 检查
php -m | grep json—— 如果报的是内置接口（JsonSerializable、Stringable、Traversable），大概率是 PHP 编译时没带对应扩展，CentOS 上要yum install php-json，Ubuntu 上是apt install php-json
IDE 补全误导你写了不存在的接口名
PHPStorm 或其他 IDE 有时会基于历史缓存或 stub 推荐一个看起来合理但实际未定义的接口名，比如 UserRepository（类名）被当成 UserRepositoryInterface（接口名）补全。
- 光标停在报错的接口名上，按
Ctrl + Click（macOS 是Cmd + Click），看能否跳转到定义；跳不到 = 名字错了或文件没加载 - 用命令行全局搜：
grep -r "interface YourInterfaceName" app/ src/ vendor/ --include="*.php" - 注意 IDE 可能缓存了旧的自动加载映射，删掉
vendor/composer/autoload_*.php和storage/framework/cache/后重试 - 如果接口定义在 trait 或抽象类里（极少见但合法），确认该文件确实被加载，且 trait 没被条件性跳过
最常被忽略的一点：报 Interface not found 时，PHP 根本还没走到“检查 implements 是否完整”这步——所以别急着去修实现类，先让 PHP 看得见那个 interface。
