Hyperf 3.0 修改代码不生效需三步：一要显式配置watch.dir为绝对路径并重启server:watch；二要注解变更后手动执行di:init-proxy重建代理类；三枚举类注解热更新失效时须改用server:start加kill -USR1 reload。
Hyperf 3.0 默认是常驻进程服务，改完代码不会自动生效——这不是你写错了，而是框架根本没重新加载。要实现“保存即刷新”，得靠 hyperf/watcher 组件配合合理配置，但光装上还不够，几个关键动作漏掉就白忙。
安装与基础启动
进入项目根目录执行：
-
composer require hyperf/watcher --dev（推荐加--dev，仅开发环境使用） - 发布配置：
php bin/hyperf.php vendor:publish hyperf/watcher，生成config/autoload/watcher.php - 用命令启动热监听：
php bin/hyperf.php server:watch
此时修改 app/ 或 config/ 下的文件，服务会自动重启并加载新代码。
必须显式配置监控路径
默认只监听 app 和 config 两个顶层目录。如果你的代码在深层路径（如 app/Http/Controller、app/Domain/User），或用了自定义命名空间（如 MyApp\Services），Watcher 不会自动发现。
- 打开
config/autoload/watcher.php - 在
'watch' => ['dir' => [...]]中添加完整绝对路径，例如：BASE_PATH . '/app/Http/Controller'、BASE_PATH . '/app/Domain'、BASE_PATH . '/MyApp' - 路径必须用正斜杠
/，Windows 的反斜杠\会导致失效 - 改完配置后，必须退出当前
server:watch进程，再重新运行命令——它不支持热重载自身配置
注解变更必须重建代理类
Hyperf 3.0+ 使用注解驱动 DI 容器和路由，所有 #[Controller]、#[GetMapping]、#[Inject] 等元数据都编译成 PHP 代理类，缓存在 runtime/container/annotation/ 目录下。
-
server:watch只负责重启进程，不触发注解扫描重建 - 新增控制器、修改
scan.paths、删过runtime/container/，或改了注解本身（比如加了新路由、改了参数绑定），都要手动执行：php bin/hyperf.php di:init-proxy - 确认
SCAN_CACHEABLE=true（默认开启），且runtime/container/annotation/下有生成的 PHP 文件；否则注解静默失效，无任何报错提示
枚举类与特殊注解的处理限制
PHP 8 枚举（enum）上的注解（如 #[OA\Property]）在 server:watch 下无法可靠热更新——这是当前 Watcher 组件的已知限制，官方尚未修复。
- 临时方案：停掉
server:watch，改用php bin/hyperf.php server:start启动 - 改完代码后，向主进程发送信号：
kill -USR1 $(cat runtime/hyperf.pid) - 该方式会 reload 整个服务，但能正确处理枚举反射变更和注解元数据刷新
