Hyperf依赖解析失败主因是注解漏写、扫描路径配置错误或接口未绑定实现；需检查@Inject等注解是否正确使用、类是否在scan_dirs范围内且含有效注解、dependencies.php中接口与实现是否绑定，并执行di:clear和di:dump刷新容器缓存。
Hyperf 依赖解析失败，通常是因为容器无法正确识别或实例化你声明的类或接口。核心原因集中在配置、注解、生命周期和类型约束几个环节，下面分情况说明排查和解决方法。
检查类是否正确启用 @Inject 或 @Value 注解
Hyperf 默认只对加了 @Inject、@Value、@Config 等注解的属性或参数进行自动注入。如果只是写了类型提示但没加注解，容器不会处理。
- 错误写法：
public UserService $userService;（PHP 8.0+ 属性类型提示，Hyperf 不识别） - 正确写法：
#[Inject] public UserService $userService;或#[Inject] private UserService $userService; - 构造函数注入也需显式标注：
public function __construct(#[Inject] UserService $service) { ... }
确认类已注册到 DI 容器或满足自动扫描条件
Hyperf 默认启用注解扫描，但前提是类在 scan.scan_dirs 配置范围内，且类本身有有效注解（如 @Controller、@Service、@Aspect 等），否则不会被自动注册为可注入对象。
- 检查
config/autoload/dependencies.php是否手动绑定了接口与实现，例如：UserInterface::class => UserService::class - 若使用 @Service，确保该类不在
scan.ignore_annotations列表中 - 运行
php bin/hyperf.php di:dump查看容器中已注册的类，确认目标类是否存在
排查循环依赖与构造函数参数问题
Hyperf 的 DI 容器不支持运行时循环依赖检测，一旦出现 A 依赖 B、B 又依赖 A 的情况，会直接抛出 ReflectionException 或 “Class not found” 类似错误（实际是反射失败）。
- 避免在构造函数中相互注入；改用 setter 注入或延迟获取（
$this->container->get(UserService::class)） - 构造函数参数必须全部能被容器解析，包括基础类型（如
string $host）需配合 @Value 或 @Config 显式注入 - 接口未绑定实现时，不要直接请求接口类型，否则报
Entry "xxxInterface" cannot be resolved
验证注解扫描是否生效及缓存是否过期
开发过程中修改注解后未刷新 DI 缓存，会导致旧的容器定义仍在生效。
- 执行
php bin/hyperf.php di:clear清除 DI 缓存 - 再执行
php bin/hyperf.php di:dump生成新映射 - 确认
config/autoload/annotations.php中scan配置路径正确，且目录下存在带注解的 PHP 文件 - CLI 模式下注意是否启用了
--no-ansi等参数干扰输出，导致误判命令未执行
不复杂但容易忽略：多数注入失败不是框架问题，而是注解漏写、路径未扫、接口未绑定这三类低级失误。按顺序检查这几点，90% 的场景都能快速定位。
