Hyperf 的 .env 文件不直接支持多数据库连接，需在 .env 中为各库定义独立变量（如 LOG_DB_HOST），再于 config/autoload/database.php 中按前缀声明连接池并引用变量，最后通过模型 $connection、on() 或 Db::connection() 显式调用。

Hyperf 的 .env 文件本身**不直接支持多数据库连接配置**，它只负责提供环境变量，真正定义多个数据库连接是在 config/autoload/database.php 中完成的。但 .env 是多库配置的“源头开关”——你需要为每个库定义独立的环境变量，再在配置文件中引用它们。

一、在 .env 中为每个库定义专属变量

不要复用同一组 DB_* 变量，否则无法区分。按语义命名，例如：

• DB_DRIVER=mysql（默认主库）
• DB_HOST=192.168.1.10
• DB_DATABASE=main_db
• DB_USERNAME=app_rw
• DB_PASSWORD=xxx
• LOG_DB_DRIVER=mysql
• LOG_DB_HOST=192.168.1.11
• LOG_DB_DATABASE=log_center
• LOG_DB_USERNAME=log_user
• LOG_DB_PASSWORD=yyy
• REPORT_DB_DRIVER=pgsql
• REPORT_DB_HOST=pg-report.internal
• REPORT_DB_DATABASE=reports
• REPORT_DB_USERNAME=rep_user
• REPORT_DB_PASSWORD=zzz

变量名必须全小写、不含点号或大写字母（如 report.db.host 会解析失败），这是 Hyperf 运行时读取 env 的硬性要求。

二、在 database.php 中引用并声明连接池

每个连接池名称必须与 env 变量前缀一致，且显式写出全部参数（不能依赖 default 继承）：

'connections' => [
  'db_write' => [
    'driver' => env('DB_DRIVER', 'mysql'),
    'host' => env('DB_HOST', 'localhost'),
    'port' => (int) env('DB_PORT', 3306),
    'database' => env('DB_DATABASE', 'hyperf'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => env('DB_CHARSET', 'utf8mb4'),
    'pool' => ['min_connections' => 2, 'max_connections' => 20],
  ],
  'log_db' => [
    'driver' => env('LOG_DB_DRIVER', 'mysql'),
    'host' => env('LOG_DB_HOST', 'localhost'),
    'port' => (int) env('LOG_DB_PORT', 3306),
    'database' => env('LOG_DB_DATABASE', 'log_center'),
    'username' => env('LOG_DB_USERNAME', 'log_user'),
    'password' => env('LOG_DB_PASSWORD', ''),
    'charset' => env('LOG_DB_CHARSET', 'utf8mb4'),
    'pool' => ['min_connections' => 1, 'max_connections' => 10],
  ],
  'report_db' => [
    'driver' => env('REPORT_DB_DRIVER', 'pgsql'),
    'host' => env('REPORT_DB_HOST', 'localhost'),
    'port' => (int) env('REPORT_DB_PORT', 5432),
    'database' => env('REPORT_DB_DATABASE', 'reports'),
    'username' => env('REPORT_DB_USERNAME', 'rep_user'),
    'password' => env('REPORT_DB_PASSWORD', ''),
    'charset' => 'utf8',
    'pool' => ['min_connections' => 1, 'max_connections' => 5],
  ],
],

注意：default 连接池建议保留但不使用，防止未显式指定连接时意外命中主库；所有连接池名（如 db_write）后续都要在代码中显式调用。

hyperframes-超帧视频

HTML 驱动的视频合成——GSAP 动画、TTS 字幕、音频响应、着色器转场

下载

三、运行时切换连接的关键写法

环境变量只是“原料”，真正生效靠代码调用。三种常用方式：

• Eloquent 模型指定连接：在模型类中加 protected $connection = 'log_db';，适用于固定走某库的读操作
• 链式 on() 切换：如 User::on('db_write')->create([...])，适合临时写入；User::on('log_db')->where(...)->get() 适合日志查询
• 原生查询绑定：必须先 Db::connection('report_db')，再 ->table('stats')->select(...)，顺序不能颠倒

事务只能绑定单个连接池，Db::connection('db_write')->transaction(...) 合法，跨库事务会直接报错。

四、验证与调试技巧

启动服务后，可通过以下方式确认配置已加载：

• 执行 php bin/hyperf.php list，检查是否识别到多个连接名
• 在控制器中打印 config('databases.connections')，确认数组结构含预期键名
• 开启 SQL 日志：'logging' => true 加入连接配置，观察实际执行的 host 和 database 是否匹配预期

如果出现 Connection [xxx] not found，优先检查 .env 变量名拼写、database.php 中连接名是否全小写、以及是否漏写了 pool 配置项。