Hyperf配置需重视环境变量优先级、注解缓存启用、热更新边界及配置中心集成；环境变量覆盖配置文件，注解缓存必须开启且cacheable设为true，核心配置不可热更新，多环境须用Nacos等配置中心。
Hyperf 的配置系统灵活且分层明确，所谓“隐藏配置技巧”，其实不是指刻意隐藏，而是指那些不常被文档强调、但对生产稳定性与部署安全至关重要的配置细节和操作习惯。掌握这些，能避开多数线上事故的源头。
环境变量优先级的实战用法
Hyperf 配置加载顺序是：环境变量 > .env 文件 > 配置文件中的 env() 函数调用 > 默认值。很多人只改 config/autoload/database.php，却忘了环境变量能直接覆盖它。
- 在 Docker 或 Kubernetes 中，用
DB_HOST=10.20.30.40等环境变量替代硬编码，无需重建镜像 - 敏感字段如
JWT_SECRET、REDIS_PASSWORD必须通过环境变量注入，绝不能写进版本库 - 测试时可临时加
HYPERF_DEBUG=true启用调试模式，上线前删掉即可，无需改代码
注解缓存必须开启（尤其生产环境）
Hyperf 大量依赖注解（如 #[Controller]、#[GetMapping]），若未启用注解缓存，每次请求都会重新扫描和解析 PHP 文件，性能损耗极大。
- 确认
config/autoload/annotations.php中'scan' => ['enable' => true]已开启 - 生产环境务必设置
'cacheable' => true，并确保runtime/container目录可写 - 首次启动后检查
runtime/container/annotation下是否生成了.php缓存文件
配置热更新的边界与风险控制
Hyperf 支持部分配置热重载（如路由、中间件），但数据库连接池、协程池、Swoole 全局参数等核心配置无法热更新，强行 reload 会触发进程重启或状态错乱。
- 修改
config/autoload/swoole.php或pool.php后，必须php bin/hyperf.php start --restart - 使用
hyperf/watcher仅适合开发阶段；生产环境禁用--watch - 若需动态调整连接池大小，应通过配置中心（如 Nacos）+ 自定义监听器实现平滑 reload
配置中心集成不是“锦上添花”，而是标配
当服务数量超过 3 个，或存在多套环境（dev/test/staging/prod），靠手动维护 .env 文件极易出错。
- 推荐接入 Nacos：Hyperf 官方提供
hyperf/config-nacos组件，支持配置监听与自动刷新 - 将非敏感配置（如超时时间、重试次数）放入配置中心，敏感项仍走环境变量
- 配置变更后，通过日志观察
ConfigCenter has updated key: database.pool.max_connections是否触发生效
