hyperf 3.0 注解不生效主因是未被扫描到，需检查 scan.paths 是否包含实际路径、执行 di:init-proxy 生成缓存、禁用 scan_cacheable 或确保 runtime/container/annotation/ 存在有效文件，并正确使用 php 8 命名参数注解语法。
Hyperf 3.0 注解不生效，90% 是因为注解压根没被扫描到，而不是写错了语法 —— 即使你把 #[Controller] 写得完全正确，只要 scan.paths 漏了目录、缓存没清、或 SCAN_CACHEABLE 开着但缓存文件根本不存在，注解就等于不存在。
scan.paths 配置漏路径是最常见死因
Hyperf 默认只扫 BASE_PATH . '/app'，但你的控制器可能在 app/Http/Controller，Service 在 app/Domain/User，甚至模块在 MyApp/。这些路径如果没显式加进 config/autoload/annotations.php 的 scan.paths，框架连文件名都不会读，更别说解析注解。
- 检查实际目录是否存在：
ls -l app/Controller（注意大小写和末尾 s） - Windows 用户避免用反斜杠：
app\Controller是错的，必须用正斜杠app/Controller - 不要写相对路径如
'app/Controller'，一律用BASE_PATH . '/app/Controller' - 自定义模块（如
MyApp）需同步改composer.json的autoload.psr-4和annotations.php两处
SCAN_CACHEABLE=true 但缓存文件缺失 = 静默失效
SCAN_CACHEABLE 不是“自动缓存开关”，它只是个条件判断：只有当 runtime/container/annotation/ 下存在合法的 PHP 缓存文件时，才会跳过扫描。而这些文件不会自己生成 —— 必须手动触发 di:init-proxy。
Hyperf 3.2.3于2026年7月30日发布，是3.2分支的官方维护版本，新增支持函数，并修复模型注释、缓存组件文档、数据库模型构建器注释和关联预加载字段等问题。
- 首次部署或改完
scan.paths后，必须运行：php bin/hyperf.php di:init-proxy - 该命令会清空
runtime/container/并重新扫描、生成注解元数据和代理类 - Docker 构建时，
runtime/container/不能被.dockerignore过滤，也不能在ENTRYPOINT里删掉再重跑 - 加密代码发布前，必须保留已生成的
runtime/container/目录及其所有.php文件
PHP 8 Attributes 写法错误导致静默忽略
Hyperf 3.0 彻底弃用 Doctrine 风格注释（/** @Controller */），也不再识别属性类型提示（public UserService $service;）。错一点，路由就 404，且无任何报错日志。
- 类级注解必须用命名参数：
#[Controller(prefix: '/api')]，不是#[Controller('/api')] - 方法级注解同理：
#[GetMapping(path: 'user')]，不是#[GetMapping('user')] - 要用
#[RequestMapping(methods: [RequestMethod::GET])]，就得use Hyperf\HttpServer\Annotation\RequestMethod - 类必须以
Controller结尾（如UserController），否则#[AutoController]不生效
ignore_annotations 删多了，整条链就断了
默认 ignore_annotations 是空数组，但一旦你加了内容，就必须想清楚：Hyperf 路由依赖「类注解 + 方法注解」两级协同。漏掉任一环，就注册不了路由。
- 比如只留
['AutoController']，却没放开GetMapping，那类能注册，方法路由全丢 - 检查是否误写了模糊匹配：
'Controller'会干掉所有含 Controller 字样的注解，包括PostMapping - 开发环境建议始终设为
[]；真要忽略自定义注解，只列具体类名，如['MyLogAnnotation'] - 执行
php bin/hyperf.php route:list，输出为空基本可锁定是ignore_annotations或扫描路径问题
最易被忽略的一点：改完 scan.paths 或 ignore_annotations 后，di:init-proxy 不够，还得顺手删掉 runtime/container/ 下除 annotation/ 和 proxy/ 外的其他子目录（比如 cache/），否则旧 DI 映射可能干扰新注解加载。
