FPM重启耗时长替换 Hyperf热更新生效方案-php教程-PHP中文网

hyperf 的 server:watch 本质是 swoole 下 worker 进程滚动重启，非 fpm 替代；其快因跳过全量加载与重建，仅重启 worker，耗时 1–3 秒；需正确配置 watch.dir、清理 runtime/container/ 并手动 init-proxy 才能确保注解等变更生效。

fpm重启耗时长替换 hyperf热更新生效方案

Hyperf 的 server:watch 不是“替换 FPM 重启”，而是绕过传统 PHP 生命周期，在 Swoole 常驻进程模型下实现文件变更 → worker 滚动重启。它无法让 FPM 变成热更新，只能帮你彻底离开 FPM。

为什么 FPM 重启慢，而 Hyperf watch 能快？

FPM 每次重启要加载全部 PHP 文件、重建 OPcache、重连数据库连接池、重新扫描注解——整个流程串行阻塞，12 秒起步很常见。Hyperf 的 server:watch 启动的是 Swoole 主从进程模型：Master 进程常驻，只负责监听文件变化；Worker 进程在变更触发时被逐个优雅终止并拉起新实例。老请求继续处理，新请求路由到新 Worker，启动耗时压缩到 1–3 秒（取决于 autoload 和 DI 初始化量）。

本质区别：FPM 是“全进程销毁+重建”，Hyperf watch 是“Worker 进程滚动替换”
server:watch 默认只 reload app/ 和 config/ 下的 PHP 文件，不碰 vendor/ —— 所以改了第三方包仍需手动重启
如果项目里用了 opcache.enable=1 且 opcache.validate_timestamps=0，反而会干扰 server:watch，建议开发环境关掉 opcache 或设为 validate_timestamps=1

watch.dir 配置漏加路径导致修改不生效

你改了 app/Domain/User/Service.php 却没反应？默认 watcher 只监控 app/ 和 config/ 两个目录，但 app/ 是个符号路径，实际扫描的是其下的子目录。若你的代码在 app/Domain，必须显式加入配置：

Hyperframes Creative

HyperFrames视频非动画创意指导，包括设计规范（frame.md/design.md）处理、配色、字体设计、旁白及节奏规划等。

下载

编辑 config/autoload/watcher.php，把 'paths' => ['app/', 'config/'] 改成 'paths' => [BASE_PATH . '/app/Domain', BASE_PATH . '/app/Http', 'config/']
路径必须用正斜杠，app\Domain（Windows 风格）会被忽略
改完配置后，必须 kill 当前 server:watch 进程再重跑命令，它不会自动 reload 自己的配置
检查是否生效：改一个已监听路径里的文件，看终端是否打印 File changed: xxx.php, reloading...

注解变更后路由 404 或 Bean 不刷新

加了个新 Controller，server:watch 重启了，但访问 404？这不是热更新失效，是注解缓存没重建。Hyperf 的 DI 容器和路由元数据都依赖 runtime/container/annotation/ 下生成的代理类，而 server:watch 只管重启进程，不管重建这些文件。

首次添加控制器、修改 scan.paths、或删过 runtime/container/ 后，必须手动执行：php bin/hyperf.php di:init-proxy
如果 SCAN_CACHEABLE=true（默认开启），但 runtime/container/annotation/ 下为空，注解就静默失效，无任何报错
枚举类（enum）上的 OpenAPI 注解（如 #[OA\Property]）热更新必然失败，这是已知限制 —— 此时停掉 server:watch，改用 php bin/hyperf.php server:start + kill -USR1 $(cat runtime/hyperf.pid)

runtime/container/ 缓存残留引发行为不一致

改了 #[Cacheable] 注解或模型字段类型，但缓存策略/验证逻辑没变？大概率是 runtime/container/ 下旧代理类还在被加载。

最稳妥清理方式：rm -rf runtime/container/ && php bin/hyperf.php di:init-proxy
不要只删 annotation/，proxy/ 和 di/ 下的文件也得清，否则 DI 容器可能复用旧定义
Docker 构建时注意：.dockerignore 不能过滤 runtime/，否则容器内始终用的是构建时缓存
PHPStorm 的 File Watcher 方案（调 reload.sh）容易残留 runtime/container/，不如原生命令可控

真正卡住人的从来不是“怎么开热更新”，而是“改了哪几处才让热更新真正覆盖到你正在调试的那一行”。路径配错、注解没刷、缓存没清——三者叠在一起，看起来就像热更新完全失效。动手前先确认 ps aux | grep watch 看进程是否由 server:watch 启动，再查 runtime/container/annotation/ 是否有对应文件，最后 curl 一下接口看日志输出是否更新。顺序不能乱。