Hyperf中接口注入失败的根本原因是未在config/autoload/dependencies.php中显式配置接口与实现类的绑定映射，导致容器无法解析接口类型；需确保接口、实现类均在扫描范围内，注入时使用接口类型，并通过di:show命令验证绑定是否生效。
Hyperf 中接口注入失败的典型表现
直接在构造函数或属性上用 @Inject 注入接口类型，运行时报 ClassNotFoundException 或提示“无法解析该类”，或者注入后调用方法抛出 Call to undefined method —— 这说明 Hyperf 没把接口和具体实现类绑定起来，不是写法错，是容器没配映射。
必须手动配置接口与实现类的绑定关系
Hyperf 默认不自动绑定接口到其实现，哪怕类名匹配（如 UserServiceInterface → UserServiceImpl）也不会自动识别。你得显式告诉 DI 容器：“这个接口，用这个类来实例化”。
- 在
config/autoload/dependencies.php中添加映射，例如：return [ App\Contract\UserServiceInterface::class => App\Service\UserServiceImpl::class, ]; - 如果实现类有依赖（比如需要
RedisFactory），确保它本身也能被容器解析（即类已自动扫描或手动注册） - 接口和实现类都需在
scan配置范围内（默认App\下都会扫），否则类根本不会被加载进容器
@Inject 时写接口名，不是实现类名
注入点必须使用接口类型，否则绑定无效。常见错误是写成实现类：
- ✅ 正确：
#[Inject] private UserServiceInterface $userService;
- ❌ 错误：
#[Inject] private UserServiceImpl $userService;
—— 这样绕过了接口绑定，且一旦换实现就得改所有注入点 - 构造函数注入同理，类型提示必须是接口：
public function __construct(private UserServiceInterface $userService) {}
测试绑定是否生效的最快方式
别等接口调用失败才排查，直接在命令行跑个简单验证：
- 执行
php bin/hyperf.php di:show "App\Contract\UserServiceInterface"，能看到输出对应实现类路径，说明绑定成功 - 如果报错 “No definition found”，检查
dependencies.php路径是否拼错、文件是否被正确加载（可加var_dump测试）、类是否存在且命名空间正确 - 修改
dependencies.php后必须重启服务（Hyperf 不热更依赖配置）
接口注入本质是容器的契约映射，不是语法糖；漏掉绑定配置，再标准的 @Inject 也无济于事。
