Hyperf的config-etcd组件默认不启用监听且不自动注册为ConfigInterface实现，需手动绑定驱动、预加载配置并开启watch才能生效。
Hyperf 项目无法自动从 Etcd 加载配置，核心原因是 hyperf/config-etcd 组件默认不启用监听，且不参与框架启动时的配置合并流程 —— 必须手动注册监听器并显式触发首次拉取。
为什么 config-etcd 装了却读不到配置？
该组件仅提供底层客户端和配置驱动，不自动注册为 ConfigInterface 实现，也不绑定到 config 生命周期。常见现象是：config('app.name') 仍返回 env 或 php 文件里的值，Etcd 中的同名 key 完全被忽略。
- 组件安装后不会修改
config/autoload/dependencies.php，需手动绑定Hyperf\Config\Contract\ConfigInterface -
EtcdDriver默认不开启 watch，配置变更不会热更新 - 首次加载依赖主动调用
load()，否则容器启动时配置为空
如何让 Etcd 配置真正生效并支持热更新？
关键在三步：替换 Config 实现、预加载、启用监听。以下操作基于 Hyperf 3.x（2.x 接口略有差异）：
- 在
config/autoload/dependencies.php中绑定自定义 Config：
return [
Hyperf\Config\Contract\ConfigInterface::class => [
'class' => Hyperf\Config\Config::class,
'constructor' => [
'data' => [],
'autoLoad' => false, // 关键：禁用自动加载，交由 Etcd 驱动控制
],
],
];
- 在
config/autoload/config.php中配置 Etcd 驱动：
'config' => [
'driver' => Hyperf\ConfigEtcd\Driver\EtcdDriver::class,
'options' => [
'host' => '127.0.0.1',
'port' => 2379,
'prefix' => 'hyperf:prod:', // 建议带环境前缀，避免混用
'timeout' => 5,
'watch' => true, // 必须设为 true 才能监听变更
],
],
- 在
src/Bootstrap/LoadEtcdConfig.php（需自行创建）中手动触发首次加载：
<?php
declare(strict_types=1);
namespace App\Bootstrap;
use Hyperf\Config\Config;
use Hyperf\ConfigEtcd\Driver\EtcdDriver;
use Psr\Container\ContainerInterface;
class LoadEtcdConfig
{
public function __invoke(ContainerInterface $container)
{
$driver = $container->get(EtcdDriver::class);
$config = $container->get(Config::class);
$config->set($driver->load()); // 主动拉取并注入
}
}
- 在
config/autoload/bootstrap.php中注册该 Bootstrap：
return [
App\Bootstrap\LoadEtcdConfig::class,
];
EtcdDriver::load() 返回什么结构？怎么写 key 才能映射到 config('database.redis.host')？
Etcd 中的 key 必须用 : 分隔，且严格匹配 config 路径。例如要覆盖 config('database.redis.host')，Etcd 中应存为：
hyperf:prod:database:redis:host
注意：prefix（如 hyperf:prod:）会自动拼接，实际存储路径是完整字符串；load() 返回的是递归嵌套数组，不是扁平 key-value。
- 不支持通配符或模糊匹配，
hyperf:prod:database:*:host无效 - 如果 Etcd 中存在
hyperf:prod:app:name和hyperf:prod:app:debug，load()返回['app' => ['name' => 'xxx', 'debug' => true]] - 空目录（无子 key）会被忽略，Etcd 中只存
hyperf:prod:app:（结尾冒号）不会生成app => []
Watch 失败或连接中断后会怎样？
默认情况下，watch 断开后 EtcdDriver 不重试，也不会 fallback 到本地配置 —— 这是最大风险点。
- watch 失败时日志仅输出
Etcd watch disconnected，无异常抛出，应用继续运行但配置冻结 - 没有内置降级策略，需自行包装
EtcdDriver，在load()失败时 fallback 到FileDriver - 连接池配置在
config/autoload/etcd.php，但hyperf/config-etcd当前版本（v3.1.0）未使用连接池，每次请求新建 gRPC 连接，高并发下易超时
真正上线前，必须补监控和降级逻辑 —— Etcd 不是“配上去就完事”的黑盒，它是配置链路中最脆弱的一环。
