注解失效主因是类未被扫描或写法错误：hyperf 3.0+仅识别#[inject]等php 8原生attribute语法，不支持类型提示或注释；scan.paths必须显式包含所有目录并执行di:init-proxy生成缓存，否则静默忽略。
注解写法错误：PHP 8 属性语法没用对
Hyperf 3.0+ 完全不识别 public UserService $userService; 这类类型提示，也不认 // @Inject 这种注释。它只解析 PHP 8 原生 Attribute 语法，错一个字符就静默忽略。
-
#[Inject]必须写在属性声明前，且属性本身不能是private（Hyperf 需要反射赋值） - 构造函数注入更安全：
public function __construct(#[Inject] UserService $service) - 如果用了
#[Inject]但类没被容器管理（比如没加#[Service]），注入照样失败——注解生效的前提是类已被扫描并注册进 DI 容器
类根本没被扫描到：scan.paths 配置漏目录
90% 的 #[Inject] 失效，不是注解写错了，而是框架压根没读你的文件。Hyperf 默认只扫 BASE_PATH . '/app'，而你的 UserService 可能放在 app/Domain/User/Service.php 或 Infrastructure/ 下。
- 检查
config/autoload/annotations.php中的scan.paths，必须显式列出所有含注解的目录，例如：[BASE_PATH . '/app', BASE_PATH . '/Domain', BASE_PATH . '/Infrastructure'] - 路径必须用正斜杠，
app\Domain\Service是无效的；也不能写相对路径如'app/Domain'，得拼全BASE_PATH . '/Domain' - 改完配置后，必须运行
php bin/hyperf.php di:init-proxy—— 否则 runtime/container/annotation/ 下没缓存文件，SCAN_CACHEABLE=true 时直接跳过扫描
缓存残留或未刷新：旧代理类干扰新注入
开发中改了注解却没效果，大概率是 runtime/container/proxy/ 或 annotation/ 下的旧文件还在起作用。Hyperf 不会自动清理它们，尤其在热更新或多次 di:init-proxy 后容易混入不一致定义。
- 清缓存不能只靠
cache:clear，得手动删掉runtime/container/整个目录 - OPcache 也可能缓存了旧类定义，确认
opcache.validate_timestamps=1，必要时调用opcache_reset() - Docker 构建时，确保
runtime/container/没被.dockerignore过滤，也别在 ENTRYPOINT 里自动rm -rf runtime/container
环境变量或配置加载时机太早
如果你在服务类里用 env('API_KEY') 初始化某个依赖，又试图用 #[Inject] 注入它，大概率失败——因为 env() 在容器初始化前就执行了，此时 .env 还没被加载。
-
env()函数不是@Value，Hyperf 没有这个注解，别混用 Spring 风格写法 - 配置文件（如
config/autoload/database.php）里直接调env('DB_HOST')是危险的，应改用延迟求值方式，比如在ServiceProvider::boot()或命令行中读取 - 验证是否加载成功：在任意 Command 里打印
getenv('YOUR_KEY')和env('YOUR_KEY')，两者结果必须一致
#[Inject] 本身，而是它依赖的整个链路：类路径 → 扫描配置 → 缓存生成 → 容器注册 → 属性赋值。任何一个环节断开，都表现为“不生效”，且无明确报错。动手前先跑一遍 ReflectionManager::getAllClasses() 看目标类在不在列表里，比反复改注解高效得多。
