hyperf注解解析器只处理php8 attributes或规范docblock（如@getmapping），完全忽略中文注释；phpparser跳过所有注释，phpdocreader仅识别@开头的合法标签，bom、空格、拼写错误或未清runtime缓存均会导致注解失效。
注解解析器根本不会读中文注释 —— 因为它压根不处理注释，只处理 PHP 8 的 #[Attribute] 或符合规范的 DocBlock 注解（如 @GetMapping），中文注释属于纯文档内容，被 Parser 直接忽略。
Hyperf 注解扫描器根本不解析普通注释
Hyperf 的注解系统依赖两个底层机制：PhpParser 解析 AST（抽象语法树），以及 PhpDocReader 专门提取 DocBlock 中的 @xxx 标签。但这两者都严格遵循 PHP 语言规范：
-
PhpParser只关心语法结构，跳过所有//和/* */内容，无论是否含中文 -
PhpDocReader只识别以@开头、后跟合法标识符（字母/下划线/数字，不能以数字开头）的标签，@中文说明或// 这里是中文全部被当作无效文本丢弃 - 如果你在类里写了
/** 中文描述 */，AnnotationCollector 里查不到任何元数据 —— 它根本没“看见”这行
文件编码不是问题，BOM 才是真凶
很多人排查时盯着 UTF-8 编码看，其实只要不是 GBK 或 ISO-8859-1 这类非 Unicode 编码，Hyperf 就能正常读取文件。真正会破坏注解识别的是 BOM（Byte Order Mark）：
- Windows 记事本保存的 UTF-8 文件常带 BOM（
EF BB BF），导致PhpParser::parse()在解析时把文件头当乱码，可能提前中断或跳过首个类定义 - 现象：某个控制器类死活不被扫描到，
AnnotationCollector::getClassesByAnnotation()返回空数组，但php -l检查语法无误 - 验证方式：
xxd -l 16 YourController.php，若开头是00000000: efbb bf...就是 BOM 作祟 - 修复命令：
sed -i '1s/^\xEF\xBB\xBF//' YourController.php（Linux/macOS）；Windows 下用 VS Code → 右下角编码菜单 → “Save with Encoding” → 选UTF-8（不含 BOM）
正则匹配失败通常是因为注解写法不合规
如果你用的是旧式 DocBlock 注解（PHP PhpDocReader 内部靠正则提取 @xxx，以下写法会导致匹配失败：
-
/** @GetMapping (path="/user") */——@后多了空格，正则/@([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)/不匹配 -
/** @GetMapping(path = "/user") */—— 等号两侧有空格，部分版本的 Reader 会因空格截断参数解析 -
/** @GETMapping */—— 类名拼错，或命名空间未正确 use（如漏了use Hyperf\HttpServer\Annotation\GetMapping;） -
/** @Inject */ private $db;——@Inject用在属性上需配合hyperf/di的属性注入开关，且该属性必须是 public 或 protected（private 需反射支持，默认开启）
最隐蔽的坑是：Hyperf 的注解扫描只跑一次，在 runtime/container 生成阶段完成。改完注解后不删 runtime/ 目录、不重跑 composer install，新注解永远进不了 AnnotationCollector。
