hyperf 项目需手动触发容器编译以提升生产环境启动性能，因默认运行时注解扫描拖慢首次请求；v3.0+ 支持 vendor/bin/hyperf compile，v2.x 需额外配置或使用 di:compile 命令。
Hyperf 项目中为什么需要手动触发容器编译
Hyperf 默认使用 AnnotationScanner 在运行时动态扫描注解并注册服务，这对开发友好但会拖慢首次请求性能。生产环境应提前编译容器，避免每次启动都重复扫描。不手动编译的话，vendor/bin/hyperf 启动时仍走运行时扫描路径，等效于没优化。
执行 php vendor/bin/hyperf compile 的前提条件
这个命令不是所有 Hyperf 版本都内置——仅 v3.0+ 官方支持原生 compile 子命令；v2.2–v2.4 需要额外安装 hyperf/framework 并确保 Hyperf\Contract\StdoutLoggerInterface 可被正确解析。常见失败现象是报错：Command "compile" is not defined 或 Class "Hyperf\Di\Compiler\Compiler" not found。
- 确认 Hyperf 版本：运行
composer show hyperf/hyperf，v3.x 才有开箱即用的compile - v2.x 用户需手动引入编译器逻辑，或改用
php bin/hyperf.php di:compile（前提是已注册该命令） - 确保
config/autoload/dependencies.php和config/autoload/annotations.php中配置合法，否则编译会跳过部分类
vendor/bin/hyperf 启动脚本是否自动调用编译结果
不会。该脚本本质是 bin/hyperf.php 的符号链接，只负责加载 Di\Container 并启动 Swoole Server，完全不感知编译产物。它读取的是运行时容器实例，除非你显式替换了容器实现。
Hyperf 3.2.3于2026年7月30日发布，是3.2分支的官方维护版本，新增支持函数，并修复模型注释、缓存组件文档、数据库模型构建器注释和关联预加载字段等问题。
- 编译后生成的文件默认在
runtime/container目录，含ContainerProxy.php和DefinitionMap.php - 要让启动脚本真正用上编译结果，必须在
bin/hyperf.php中将Hyperf\Di\Container替换为Hyperf\Di\Compiler\Container - 典型替换写法：
$container = new \Hyperf\Di\Compiler\Container($definitionLoader);，且需确保$definitionLoader指向编译生成的DefinitionMap
编译后启动变慢或报 ClassNotFoundException 怎么办
这是最常踩的坑：编译过程依赖当前 autoloader 状态，而 Composer 的 autoload 机制在不同环境可能不一致。比如 Docker 构建时未运行 composer dump-autoload -o，会导致编译时类找不到，但运行时又因 PSR-4 自动加载“侥幸”成功。
- 务必在和运行环境一致的 PHP 版本、扩展、autoloader 模式下执行编译
- 检查
runtime/container/DefinitionMap.php是否包含你期望注入的类名；若为空或条目极少，说明扫描路径配置有误（如scan.scan_dirs漏了app/） - 启用
debug模式（'debug' => trueinconfig/autoload/annotations.php）可看到扫描日志，定位漏扫原因
编译不是一劳永逸的事——只要改了注解、新增了 @Inject 或调整了 dependencies.php，就得重新编译。别把它当成部署脚本里跑一次就完事的操作。
