Hyperf多数据库配置需四步：先安装hyperf/database等依赖，再在databases.php中定义default和tenant_meta等完整连接配置，接着在模型中用$connection属性或DB::connection()指定连接，最后通过TenantContext中间件实现租户级动态路由。
Hyperf 初始化项目并配置多数据库连接，核心在于先装依赖、再配多库、最后验证可用。它不是简单改个配置就完事，而是要结合 Hyperf 的 DI 容器机制、连接池设计和模型绑定逻辑来组织。下面分四步说清楚。
一、初始化项目并安装必要组件
从官方骨架起步，确保基础环境干净：
- 执行
composer create-project hyperf/hyperf-skeleton my-saas - 进入目录：
cd my-saas - 安装数据库核心组件：
composer require hyperf/database hyperf/db-connection - 如需 Redis 或其他扩展（比如 JWT），按需追加：
composer require hyperf/redis firebase/php-jwt
二、配置多个数据库连接
Hyperf 使用 config/autoload/databases.php 管理连接，支持多组命名配置。例如同时接入主业务库和租户元数据库：
- 在
databases.php中定义两个连接：一个default（主业务），一个tenant_meta（存租户信息） - 每个连接都需完整声明
driver、host、database、username、password及pool参数 - 注意
prefix可设为空或统一前缀，避免跨库表名冲突 - 若用 Docker，
host填容器名（如mysql-main/mysql-meta），并确保网络互通
三、在模型中指定连接
Hyperf 模型默认走 default 连接，切换多库靠 $connection 属性或运行时绑定：
- 元数据模型（如
Tenant.php）显式指定：protected $connection = 'tenant_meta'; - 业务模型（如
User.php）保持默认，或根据租户上下文动态切换（见下步） - 若需临时切库查询，可用
DB::connection('tenant_meta')->table(...)->get() - 不建议在控制器里硬编码连接名，应封装进 Service 层做隔离
四、配合多租户实现运行时连接路由
真正实用的多库，往往需要“按租户自动选库”。Hyperf 支持通过 TenantContext + 中间件 + 模型事件联动完成：
- 在
TenantResolveMiddleware解析出tenant_id后，调用TenantContext::set($id, $code) - 重写基类模型
BaseTenantModel，在boot或creating钩子中读取上下文，并设置$this->connection - 对共享库模式（行级隔离），只需注入
tenant_id到所有查询；对独立库模式，则根据tenant_code动态切换connection名称 - 务必在协程结束前清理上下文（
TenantContext::clear()），防止连接错乱
整个流程不复杂但容易忽略细节，关键是把连接配置、模型绑定、上下文传递三者串起来。跑通一次后，后续增删库只需复制配置+调整模型属性即可。
