注解失效主因是proxy缓存未重建，watch命令仅重启worker，不触发注解扫描与proxy生成；需手动清空runtime/container、runtime/proxy、runtime/cache目录，并确保autoload正常。
注解失效不是热更新本身的问题，而是proxy缓存没被正确重建
为什么php bin/hyperf.php watch不自动刷新proxy文件
Hyperf 的 watch 命令只监听 PHP 文件内容变更并重启 Worker，但它不会触发注解扫描和 proxy 生成流程。也就是说，即使你改了 #[Controller] 或新增了 #[Inject]，只要 runtime/container/proxy/ 下的代理类没重写，框架就继续用旧的缓存——而旧缓存里压根没有新注解信息。
常见错误现象：
- 新增路由注解后访问 404
- 修改
dependencies.php后#[Inject]报 “must not be accessed before initialization” - 删掉某个
#[Aspect]类，切面逻辑仍生效
根本原因：proxy 缓存是静态快照，watch 不管它存不存在、对不对。
清理 proxy 缓存的正确姿势
别只删 runtime/container，要确保以下路径被清空：
-
runtime/container（主要存放注解元数据数组） -
runtime/proxy（部分版本或配置下会放在这里） -
runtime/cache（避免 DI 容器加载旧的缓存配置）
推荐命令（保留 runtime/logs）：
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
rm -rf runtime/container runtime/proxy runtime/cache
注意：rm -rf runtime/* 会连 logs 一起删，生产排查时慎用；find runtime -mindepth 1 -delete 在某些 Windows + Docker 环境下因权限或挂载问题可能失败，不如显式指定子目录安全。
什么时候必须手动清理 proxy
以下场景不清理就大概率注解失效：
- 新增/删除自定义注解类（如
#[MyAuth]），且该注解实现了AnnotationInterface - 升级
hyperf/di或symfony/finder（尤其 v7.0+ 后 Finder 过滤逻辑变更，会导致扫描漏文件） - 在 Windows + Docker 环境下，文件数量 >60 且类名排序靠后（Finder 遍历顺序不稳定，可能跳过部分文件）
- 从 Git 切换分支后，注解结构有变动（如把
#[Controller]从类移到方法上）
性能提示：首次启动时扫描耗时长是正常的；但热更新阶段反复删 proxy 并非最优解——更稳妥的做法是在开发脚本中把 di:init-proxy 和 watch 组合成一键命令，例如：
php bin/hyperf.php di:init-proxy && php bin/hyperf.php watch
proxy 生成失败的隐蔽信号
proxy 缓存没生成成功，不一定报错，但会有这些迹象：
-
runtime/container目录为空，或只有annotations.php却没有inject.php/aspect.php - 启动日志里没出现
Scan app completed, took X ms - 用
php bin/hyperf.php di:scan手动执行时卡住，或报Class not found（说明 AST 解析失败，常见于语法错误或 PHP 8.2+ 属性语法兼容问题）
最容易被忽略的一点：proxy 生成依赖 vendor/autoload.php 能正常加载所有类。如果 composer 自动加载规则损坏（比如 psr-4 映射路径写错），扫描过程会静默跳过整个命名空间——此时删 runtime 也没用，得先跑 composer dump-autoload。
