hyperf 启动慢主因是注解扫描和 proxy 类生成；watch 模式禁用缓存致每次重启等同冷启动，应禁用并改用 start 命令配合 runtime 目录可写、正确扫描路径配置及 proxy 文件存在来启用缓存。

Hyperf 启动慢，八成出在注解扫描和 Proxy 类生成环节。热加载（php bin/hyperf.php watch）在开发阶段方便，但会彻底关闭缓存机制，每次改代码都强制全量重扫——这不是“快”，是“假装快”，实际把启动耗时摊到了每次变更上。

为什么 watch 会让启动变慢十倍

Hyperf 的 watch 模式默认禁用所有缓存生成逻辑：不写 runtime/container/proxy/ 下的代理类文件，也不序列化注解元数据。每次文件变更后重启，都等同于一次全新冷启动——重新反射每个类、重新解析 #[Controller]、#[Inject]、重新生成路由表和 AOP 代理代码。

• 现象：watch 下首次启动可能 2–3 秒，改一个 .php 文件后重启又卡 2 秒以上，反复触发
• 本质：它绕过了「以空间换时间」的设计初衷，把本该只做一次的重操作，变成高频重复劳动
• 适用场景：仅限极小项目或调试单个文件时临时启用；中大型项目务必禁用

如何正确开启 Proxy 缓存并确保生效

Proxy 缓存不是开关，而是一套依赖明确目录权限 + 配置显式声明 + 启动命令配合的组合动作。缺一不可。

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• 确认 runtime/ 目录可写：chmod -R 755 runtime/，尤其检查 runtime/container/proxy/ 是否存在且可写入
• 检查 config/autoload/scanner.php 中是否定义了扫描路径，例如：'scan' => ['paths' => ['app'] ]；空配置或路径错误会导致扫描跳过，缓存自然为空
• 必须使用 php bin/hyperf.php start 启动（而非 watch），且首次启动会自动触发缓存生成；后续启动只要 runtime/container/proxy/ 下有有效文件，就直接加载，不再反射
• 验证是否生效：启动后查看 runtime/container/proxy/ 目录下是否有大量 *Proxy.php 和 annotations.php 文件；没有则说明扫描未执行或被跳过

哪些注解会触发 Proxy 类生成

不是所有注解都导致 Proxy 类落地。只有涉及运行时行为劫持的注解，才会让 Hyperf 生成代理类——这是性能开销的主因。

• 必生成 Proxy 的： #[Aspect]、#[Middleware]、#[AutoController]（如果启用）、带切面匹配的 #[Controller]
• 只写入元数据缓存（不生成 .php 文件）的： #[Inject]、#[Value]、#[GetMapping] —— 它们只影响 annotations.php 数组内容，不增加文件 IO 和 include 开销
• 建议：高频请求路径上的 Controller 尽量避免嵌套 #[Aspect]，或把切面逻辑下沉到 Service 层，减少 Proxy 类数量

清理缓存后忘记重启 = 白清

执行 rm -rf runtime/container/proxy/ 或 php bin/hyperf.php gen:proxy 后，若不重启进程，旧的 Proxy 类仍在内存中继续运行。缓存清理只对下一次 start 生效。

• 常见误操作：清完缓存 → 看日志没报错 → 认为已生效 → 继续用 watch 测试 → 结果还是慢
• 正确流程：删缓存 → kill -9 所有 hyperf 进程 → php bin/hyperf.php start
• 额外提醒：gen:proxy 命令只是手动触发生成，并不自动重启；它适合 CI 构建阶段预生成，但本地开发仍需配合重启

Proxy 缓存的真正价值不在“第一次快”，而在“第二次及以后几乎不花时间”。很多人卡在权限、路径、启动方式这三个点上，反复折腾却以为是框架问题。盯住 runtime/container/proxy/ 目录是否存在有效文件，比看启动日志更可靠。