企业官网建设流程全解析

• 后端
• Web框架
• 微服务
• RPC框架
• 异步编程

Watcher 是 Hyperf 框架中用于解决启动扫描耗时、并实现文件变更后即时重启服务的开发辅助组件。本文以官方文档为主体，结合组件源码，完整讲解其安装、配置、四种监听驱动的选型与工作原理、启动方式（含 Docker 用法）以及底层「增量收集 + 重启」的运行机制，帮助你快速建立一套适合日常开发的本地热更新工作流。

适用前提：该组件面向 Hyperf2.0及以上版本，且仅适用于开发环境，请勿在生产环境中使用。

为什么需要 Watcher：2.0 时代的启动性能背景

从2.0版本开始，Hyperf 使用BetterReflection来收集abstract syntax tree (AST)与反射数据，因此扫描速度相比1.1版本明显变慢。首次启动应用时因为没有扫描缓存存在，会格外缓慢；后续启动虽然会快一些，但由于每次都需要实例化BetterReflection，启动时间依然偏长。

Watcher 组件正是为了解决上述启动问题而设计的，它的职责有两个：

1. 通过collector-reload.php实现增量扫描与收集，避免每次启动都做全量扫描（详见下文「运行机制」一节）；
2. 在文件被修改后立即重启应用，实现开发期的热更新体验。

安装

Watcher 属于开发辅助工具，应作为dev依赖安装：

composer require hyperf/watcher --dev

配置

发布配置

安装完成后，执行以下命令将组件的默认配置发布到项目根目录（发布目标为.watcher.php，对应源码见 ConfigProvider.php）：

php bin/hyperf.php vendor:publish hyperf/watcher

配置说明

官方文档给出的配置项如下：

发布后的默认配置文件（见 publish/watcher.php）实际内容如下，其中轮询间隔在代码中的真实键名为watch.scan_interval（文档表格中的watch.interval即对应此项）：

<?php use Hyperf\Watcher\Driver\ScanFileDriver; return [ 'driver' => ScanFileDriver::class, 'bin' => PHP_BINARY, 'watch' => [ 'dir' => ['app', 'config'], 'file' => ['.env'], 'scan_interval' => 2000, ], 'ext' => ['.php', '.env'], ];

从 Option.php 的构造函数可以看到各配置项的解析逻辑：driver、bin、command、watch.dir、watch.file、watch.scan_interval、ext均为可选配置，缺省时使用类属性中的默认值（见 Option.php）：

• driver默认Hyperf\Watcher\Driver\ScanFileDriver::class；
• bin默认PHP_BINARY（即当前 PHP 可执行文件路径）；
• command默认vendor/hyperf/watcher/watcher.php start，即通过该脚本拉起服务进程；
• watchDir默认['app', 'config']，watchFile默认['.env']，ext默认['.php', '.env']；
• scanInterval默认2000（毫秒），且getScanInterval()保证非法值（<= 0）时回退到2000（见 Option.php）。

另外还有一个细节：getBin()在 bin 路径包含空格时会自动加上双引号，避免命令解析出错（见 Option.php）。

命令行参数

server:watch命令（实现见 WatchCommand.php）额外支持以下选项，可在不修改配置文件的情况下临时调整监听行为：

例如，临时把src目录也纳入监听、且本次不重启服务：

php bin/hyperf.php server:watch -D src -N

命令行传入的目录/文件会与配置中的默认值通过array_unique(array_merge(...))合并去重（见 Option.php），这一行为在单元测试 WatcherTest.php 中有明确验证：默认['app', 'config']合并['src']后得到['app', 'config', 'src']。

驱动支持与选型

Watcher 通过驱动（Driver）抽象了不同的文件监听实现，所有驱动都实现统一的 DriverInterface.php（仅一个watch(Channel $channel): void方法），并由 Watcher.php 依据配置实例化。官方文档列出的驱动如下：

ScanFileDriver：纯 PHP 轮询，默认首选

这是默认驱动，不依赖任何系统级扩展。其核心思路非常简单：每隔scan_interval毫秒，对监听目录内所有匹配ext的文件以及监听文件列表计算内容md5（见 ScanFileDriver.php），再与上一轮的 md5 快照做差集：

• 值不同的文件视为「修改」；
• 新增的 key 视为「新增」，直接推入 Channel；
• 消失的 key 视为「删除」，此时仅输出Delete files must be restarted manually to take effect.的警告日志，不会自动触发热更新（见 ScanFileDriver.php）。

因为是全量计算 md5，文件数量较大时轮询开销会相应上升，此时可考虑下面的系统级驱动。

FswatchDriver：基于 fswatch 的事件驱动

依赖fswatch工具，构造时若which fswatch无输出会直接抛出InvalidArgumentException（见 FswatchDriver.php）。它通过proc_open启动 fswatch 进程并读取其标准输出，按行解析出变更文件路径，再过滤掉不在ext内的文件后推入 Channel。在非 Darwin（macOS）平台会追加-m inotify_monitor、--event Created --event Updated --event Removed --event Renamed等参数（见 FswatchDriver.php），即使用内核 inotify 机制，响应更快、开销更低。

fswatch 安装方式：

Mac：

brew install fswatch

Ubuntu/Debian：

apt-get install fswatch

Linux（源码编译安装）：

wget https://github.com/emcrisostomo/fswatch/releases/download/1.14.0/fswatch-1.14.0.tar.gz \ && tar -xf fswatch-1.14.0.tar.gz \ && cd fswatch-1.14.0/ \ && ./configure \ && make \ && make install

FindDriver：基于 find 的修改时间扫描

依赖系统find命令，通过find <目录> -mmin <分钟> -type f -print找出最近若干分钟内被修改过的文件（见 FindDriver.php）。在 macOS 上需要gfind（即brew install findutils安装的 GNU find），否则构造时直接抛异常（见 FindDriver.php）；在 Linux 上还会探测是否为 BusyBox 的find，以决定是否支持小数分钟参数（见 FindDriver.php）。

FindNewerDriver：基于 find -newer 的增量扫描

同样依赖find，但使用-newer与临时文件（/tmp/hyperf_find.php）配合，通过交替更新两个临时文件的 mtime 来标记「上一次扫描时刻」，从而只比对「比标记文件更新」的文件（见 FindNewerDriver.php）。相比 FindDriver 按固定分钟窗口扫描，这种方式能更精确地捕捉两次轮询之间发生的变化。

驱动如何选择

• 追求零依赖、开箱即用：ScanFileDriver（默认）；
• 文件数量大、希望响应快：FswatchDriver（需先安装 fswatch）；
• 已有find/gfind环境、不想装额外工具：FindDriver / FindNewerDriver。

启动

由于目录结构的原因，启动命令必须在项目根目录下执行：

php bin/hyperf.php server:watch

Docker 启动

在 Docker 中配置热更新时，需要在 Dockerfile 中把入口点指定为：

ENTRYPOINT ["php", "/opt/www/bin/hyperf.php", "server:watch"]

注意：当前官方文档提示Alpine Docker 环境下存在轻微问题，该问题计划在后续版本中改进，在 Alpine 容器中如遇到异常可先排查此已知限制。

运行机制：增量收集与自动重启如何协同

server:watch命令在 WatchCommand.php 中完成配置加载（默认配置 +.watcher.php合并 + CLI 参数覆盖）后，即调用 Watcher.php 的run()进入主循环。整个运行流程可以拆成四个阶段：

① 重新生成自动加载映射

启动时先执行composer dump-autoload -o --no-scripts（见 Watcher.php），保证新增类能被 Composer 的 classmap 正确命中，为后续增量反射做好准备。

② 启动服务

随后立即拉起服务进程。这里有两个硬性前提（见 Watcher.php）：

• 必须配置server.settings.pid_file，否则抛出FileNotFoundException；
• 必须将server.settings.daemonize设为false（守护进程模式下无法配合重启逻辑），否则抛出InvalidArgumentException。

③ 驱动监听与增量收集

驱动在协程中监听文件变更，并将变更文件路径推入容量为 999 的 Channel。主循环pop(0.001)取出文件后，会执行：

php vendor/hyperf/watcher/collector-reload.php <变更文件路径>

即调用 collector-reload.php 逐文件做增量收集，核心逻辑在 Process.php 中：

1. 用Ast解析变更文件的 AST，通过RewriteClassNameVisitor提取类名与路径元数据（见 Process.php）；若不是类定义（例如.env等非 PHP 文件），直接返回；
2. require该文件，用ReflectionManager::reflectClass重新反射；
3. 清空该类的旧收集器数据，再用Scanner->collect()重新收集注解（见 Process.php）；
4. 重新生成 AOP 代理类（ProxyManager），清理过期的 aspect 类文件，并把最新收集结果序列化写入runtime/container/scan.cache（见 Process.php）。

这样，单纯修改类文件时无需全量重启，即可让注解、AOP 切面等元数据在下一轮生效，这也是 Watcher 缓解 2.0 扫描开销的关键手段。

④ 批次结束后的服务重启

当 Channel 在极短时间内（0.001s）没有新文件到来、且本轮已积累变更文件时，主循环调用restart(false)（见 Watcher.php）：先向旧进程发送SIGTERM，再通过proc_open以bin + command拉起新进程（见 Watcher.php）。如果使用了-N/--no-restart，则跳过整个重启步骤（见 Watcher.php）。

值得一提的细节：在发送终止信号之前，会派发BeforeServerRestart事件（见 Watcher.php），组件自带的 ReloadDotenvListener.php 监听该事件并调用DotenvManager::reload()重新加载.env，保证重启后的进程携带最新的环境变量。

注意事项与已知问题

• 仅限开发环境：组件会在文件变更时反复重启服务，生产环境请勿使用；
• 必须运行在项目根目录：启动命令依赖相对目录结构；
• 删除文件不触发热更新：删除操作只会输出警告日志，需手动重启才能生效（对应 ScanFileDriver.php 的实现）；
• 修改.env需手动重启：官方文档明确说明.env的修改需要手动重启才能生效；
• Alpine Docker 环境存在轻微问题：官方文档标注为已知限制，将在后续版本改进；
• daemonize必须为false、且必须配置pid_file：否则 watcher 无法完成「停止旧进程 → 拉起新进程」的重启流程，会在启动阶段直接抛异常。

小结

Watcher 组件用「增量收集 + 批量重启」的组合，既规避了 2.0 时代全量扫描带来的启动延迟，又提供了文件变更即重启的开发体验。实际使用时，先安装hyperf/watcher --dev并发布.watcher.php配置，按需在四种驱动中选择（默认 ScanFileDriver 零依赖即可工作），然后从项目根目录执行php bin/hyperf.php server:watch即可。掌握-D/-F追加监听范围、-N免重启模式以及daemonize=false、pid_file等前置条件，就能让热更新在本地开发中稳定落地。

• 后端
• Web框架
• 微服务
• RPC框架
• 异步编程