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% 以上的启动时间。
