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/ 目录是否存在有效文件，比看启动日志更可靠。
