hyperf注解路由需缓存以避免每次启动重复扫描ast：未启用时，启动需递归解析所有php文件，i/o与cpu开销大；启用后序列化结果至runtime/container/annotations.php，后续直接加载。

Hyperf 3.0 默认在开发环境启用注解扫描，但生产环境必须显式开启注解缓存，否则每次启动都会重新扫描全部类文件，导致启动极慢——尤其当项目模块多、注解密集时，启动耗时可能从秒级升至数十秒。

为什么注解路由需要缓存

Hyperf 的 @GetMapping、@PostMapping 等路由注解不靠运行时反射实时解析，而是通过注解扫描器（AnnotationScanner）在启动阶段构建路由映射表。若未启用缓存，每次启动都需递归扫描 app/、src/ 下所有 PHP 文件并解析 AST，I/O 和 CPU 开销大。启用缓存后，扫描结果序列化为 PHP 数组并写入 runtime/container/annotations.php，后续启动直接加载，跳过扫描。

开启注解缓存的必要配置

只需两步，无需改代码：

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• 确保 config/autoload/annotations.php 存在且内容完整（Hyperf 3.0+ 脚手架默认已提供）
• 在 .env 中设置：
  ANNOTATION_SCAN_ENABLE=true
• 确认 runtime/ 目录可写（Web 服务器用户需有写权限）

验证是否生效

启动后检查两个关键点：

• 查看 runtime/container/annotations.php 是否生成（非空 PHP 数组文件）
• 首次启动含 [INFO] Annotation scanning completed；
  第二次启动应跳过该行，直接进入容器构建阶段
• php bin/hyperf.php start，可加 -v 参数观察扫描耗时是否消失

进阶建议：CI/CD 中预生成缓存

避免上线时首次启动仍慢，推荐在构建阶段预生成注解缓存：

• 在 CI 流程末尾执行：
  php bin/hyperf.php annotation:scan --force
• 将生成的 runtime/container/annotations.php 打包进部署镜像或发布包
• 生产环境启动时即使 ANNOTATION_SCAN_ENABLE=false，只要缓存文件存在且有效，Hyperf 仍会自动加载

不复杂但容易忽略，开对了能省掉 70% 以上的启动时间。