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 默认只扫
，但你的控制器可能在
，Service 在
，甚至模块在
。这些路径如果没显式加进
的
，框架连文件名都不会读，更别说解析注解。
检查实际目录是否存在：
（注意大小写和末尾 s）
Windows 用户避免用反斜杠：
是错的，必须用正斜杠
不要写相对路径如
，一律用
自定义模块（如
）需同步改
的
和
两处
SCAN_CACHEABLE=true 但缓存文件缺失 = 静默失效
不是“自动缓存开关”，它只是个条件判断：只有当
下存在合法的 PHP 缓存文件时，才会跳过扫描。而这些文件不会自己生成 —— 必须手动触发
。
首次部署或改完
后，必须运行：
该命令会清空
并重新扫描、生成注解元数据和代理类
Docker 构建时，
不能被
过滤，也不能在
里删掉再重跑
加密代码发布前，必须保留已生成的
目录及其所有
文件
PHP 8 Attributes 写法错误导致静默忽略
Hyperf 3.0 彻底弃用 Doctrine 风格注释（
），也不再识别属性类型提示（
）。错一点，路由就 404，且无任何报错日志。
Hyperf 3.1.66
本页面提供企业级 PHP 协程框架 Hyperf 3.1.66 版本的官方源码下载与完整更新日志。重点解析 v3.1.66 版本中新增的 gRPC 多客户端负载均衡支持、Pool 连接池全量刷新、Guzzle 持久化 Cookie 以及数据库 JSON 包含键查询等核心优化特性。
下载
类级注解必须用命名参数：
，不是
方法级注解同理：
，不是
要用
，就得
类必须以
结尾（如
），否则
不生效
ignore_annotations 删多了，整条链就断了
默认
是空数组，但一旦你加了内容，就必须想清楚：Hyperf 路由依赖「类注解 + 方法注解」两级协同。漏掉任一环，就注册不了路由。
比如只留
，却没放开
，那类能注册，方法路由全丢
检查是否误写了模糊匹配：
会干掉所有含 Controller 字样的注解，包括
开发环境建议始终设为
；真要忽略自定义注解，只列具体类名，如
执行
，输出为空基本可锁定是
或扫描路径问题
最易被忽略的一点：改完
或
后，
不够，还得顺手删掉
下除
和
外的其他子目录（比如
），否则旧 DI 映射可能干扰新注解加载。
BASE_PATH . '/app'app/Http/Controllerapp/Domain/UserMyApp/config/autoload/annotations.phpscan.pathsls -l app/Controllerapp\Controllerapp/Controller'app/Controller'BASE_PATH . '/app/Controller'MyAppcomposer.jsonautoload.psr-4annotations.phpSCAN_CACHEABLEruntime/container/annotation/di:init-proxyscan.pathsphp bin/hyperf.php di:init-proxyruntime/container/runtime/container/.dockerignoreENTRYPOINTruntime/container/.php/** @Controller */public UserService $service;#[Controller(prefix: '/api')]#[Controller('/api')]#[GetMapping(path: 'user')]#[GetMapping('user')]#[RequestMapping(methods: [RequestMethod::GET])]use Hyperf\HttpServer\Annotation\RequestMethodControllerUserController#[AutoController]ignore_annotations['AutoController']GetMapping'Controller'PostMapping[]['MyLogAnnotation']php bin/hyperf.php route:listignore_annotationsscan.pathsignore_annotationsdi:init-proxyruntime/container/annotation/proxy/cache/