ThinkPHP 数据库配置文件 config/database.php 逐行解读【干货】

提到 ThinkPHP 的 config/database.php，很多开发者第一反应是：这不过是个填上数据库地址、用户名、密码就能用的配置文件。但实际踩过坑的人都知道，这里面门道不少。它本质上是一套结构严谨、键名敏感、层级分明的连接定义机制——顶层键写错一个，整个配置就静默失效；漏掉一个 env() 调用，你在 .env 文件里改一百遍也没用；SSL 证书路径写成相对路径，连上了也查不到证书。这些细节，全藏在每一行代码里。

default 必须指向 connections 里的真实键名

'default' => 'mysql' 这行代码，看着简单，其实是个关键节点。它的值必须和 connections 数组中某个子项的键名完全一致——比如 'mysql' 或 'user_db'，而不能是驱动类型（比如 'pdo_mysql'），也不能是空字符串或随便写个名字。否则框架根本找不到默认连接，直接报 Connection not found 错。

• ✅ 正确写法：'default' => 'master'，且 connections 里存在 'master' => [...]
• ❌ 错误写法：'default' => 'mysql'，但 connections 里只有 'primary' 和 'slave'
• ⚠️ 值得注意：default 只决定 Db::table() 这类无参调用走哪个连接，它不参与多库切换的逻辑判断

connections 是唯一真正生效的连接定义区

所有数据库连接都必须放在 'connections' 这个关联数组下面，每个子项就是一个完整的连接配置。框架只会认这个键下的内容，其他地方写的 'hostname'、'database' 这些字段，只要不在 connections 的某个子项里，全部被忽略。

• 每个连接必须包含 'type'（比如 'mysql'）、'hostname'、'database'、'username'、'password'
• 'hostport' 建议明确写出来，别指望 PDO 的默认端口——MySQL 是 3306，但 PostgreSQL 是 5432，依赖默认值迟早要出问题
• 'charset' 强烈建议设为 'utf8mb4'，否则 emoji 存不进去改起来很麻烦
• 'prefix' 可以是空字符串，但不要省略，不写可能触发意外的表名拼接

敏感字段必须用 env() 读取，默认值只做开发兜底

密码、主机、端口这些参数，绝不能在 database.php 里硬编码。必须通过 env('DB_PASSWORD', 'root') 这种方式加载，同时确保 .env 文件存在且格式正确。

• .env 文件要放在项目根目录，变量名全大写加下划线，比如 DB_HOST=192.168.1.100
• 等号两侧不能有空格，否则 env() 会返回 null，导致连接被拒（报错 SQLSTATE[HY000] [1045]）
• 修改 .env 文件后，必须执行 php think clear:config，否则缓存里的还是旧值
• CLI 模式下要确认 thinkEnv::load() 已经被调用，不然 env() 返回 null，排查起来让人头疼

SSL 和底层参数只能塞进 params 数组

想启用 MySQL SSL？别往 DSN 字符串里拼 ?ssl_mode=REQUIRED，ThinkPHP 不解析这种写法。唯一有效的方式是通过 'params' 数组，而且必须用 PDO 常量加上绝对路径。

• 证书路径必须用绝对路径，比如 PDO::MYSQL_ATTR_SSL_CA => '/etc/ssl/mysql/ca.pem'
• 如果服务端要求双向认证，还得提供 PDO::MYSQL_ATTR_SSL_CERT 和 PDO::MYSQL_ATTR_SSL_KEY
• SSL 模式必须用整数常量：PDO::MYSQL_ATTR_SSL_MODE_REQUIRED，写字符串 'REQUIRED' 会被直接忽略
• 持久连接、超时设置这些，也走 params，例如 PDO::ATTR_PERSISTENT => true

不复杂，但容易忽略。每一行都在做校验，每一对引号都在影响连接成败。把这些细节理清楚了，配置才能稳如磐石。