thinkphp数据库配置

ThinkPHP数据库配置详解：从连接到优化的完整指南

ThinkPHP数据库配置的核心答案：在config/database.php中统一管理连接参数，通过环境变量区分不同场景，用env()函数读取敏感信息，连接失败时优先检查主机、端口、认证和缓存问题。这篇文章把配置这件事拆开揉碎，从最基础的连接写法到多库、读写分离、调试技巧，全部覆盖，如果你正在用ThinkPHP 6或8，建议直接对照着改。

为什么你的ThinkPHP数据库配置总出问题

新手最容易栽的坑是以为改完database.php就完事，结果页面报”数据库连接错误”或者”PDOException”。绝大多数连接失败不是代码问题，而是环境不一致，本地开发用localhost，线上用0.0.1或独立IP，端口默认3306但只要装过集成环境就可能被改成3307，数据库名、用户名、密码里只要有空格或特殊字符，也会直接卡在认证环节。

行业共识认为,配置前先做三件事：用php think version确认框架版本，用php think run启动内置服务器，再用php think make:command生成一个测试命令输出env('database.hostname')值，这三步能排除一半以上的低级错误。

配置文件里的每个字段到底是什么意思

ThinkPHP的config/database.php返回一个数组，默认结构如下：

return [
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'type' => 'mysql',
            'hostname' => env('database.hostname', '127.0.0.1'),
            'database' => env('database.database', 'think'),
            'username' => env('database.username', 'root'),
            'password' => env('database.password', ''),
            'hostport' => env('database.hostport', '3306'),
            'charset' => 'utf8mb4',
            'prefix' => env('database.prefix', ''),
            'debug' => true,
        ],
    ],
];

• default决定用哪个连接，多库配置时改成对应键名。
• type目前主流是mysql，如果你用PostgreSQL或SQLite，改成相应驱动。
• hostname别写localhost，很多Linux环境解析慢，用0.0.1直连更快。
• charset建议统一utf8mb4，别用utf8，否则emoji和特殊字符会变问号。
• prefix是表前缀，比如tp_，查询时自动拼接。

修改完配置文件后,必须执行

php think clear清理缓存，ThinkPHP会把配置缓存到runtime/目录，不清理的话改了等于白改。

thinkphp配置多个数据库的两种标准做法

项目大了经常需要连多个库,比如订单库和用户库分开，这里有两种主流方案。

在connections里注册多个连接

直接在connections数组中新增一个键，比如mysql_orders，参数跟主库一样，使用时：

$db = Db::connect('mysql_orders');
$result = $db->table('order')->where('status', 1)->select();

或者在模型内定义$connection属性：

class Order extends Model
{
    protected $connection = 'mysql_orders';
}

动态切换连接（适合分库分表场景）

如果请求来了才知道用哪个库,可以动态设置：

Db::setConfig([
    'type' => 'mysql',
    'hostname' => '192.168.1.2',
    'database' => 'db_app',
    // ...
]);

注意这种写法每次请求都会缓存配置,务必在操作结束后调用Db::clear()。

多库配置的核心规则：一个连接对应一套参数，别把多个库塞进同一个连接再用database.xxx跨库查询。跨库关联查询性能极差，而且如果库在不同服务器上根本连不上。

thinkphp数据库连接失败怎么办：排查步骤

遇到连接失败,先别急着改代码，按照下面的顺序检查。

验证基础网络和端口

在服务器上执行telnet 127.0.0.1 3306或nc -zv 127.0.0.1 3306，如果端口不通，检查防火墙和MySQL是否启动，云服务器还要看安全组规则有没有放行3306。

检查证书和认证方式

MySQL 8.x默认使用caching_sha2_password，而PHP 7.2以下或较旧的PDO驱动可能不支持，解决方法是登录MySQL执行：

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '你的密码';
FLUSH PRIVILEGES;

或者升级PHP到7.4以上并安装mysqlnd。

确认框架读取的是哪个配置

永远不要直接改config/database.php里的默认值而不看.env文件，ThinkPHP会优先读取.env，如果你在.env里写了：

[database]
hostname = 127.0.0.1
database = think
username = root
password = 
hostport = 3306

那么config/database.php

里env('database.hostname', '127.0.0.1')的默认值会被覆盖，用php think route:list或写个探针打印config('database.connections.mysql.hostname')确认实际值。

看日志里的具体错误码

runtime/log/目录下日志会包含类似SQLSTATE[HY000] [2002] Connection refused的信息。2002代表主机或端口不通，1045代表用户名密码错误，1049代表数据库不存在，1044代表权限不足，对症下药。

数据库读写分离配置实战

高并发环境要求读写分离,ThinkPHP原生支持主从配置，在connections.mysql下增加read和write两个子数组：

'read' => [
    'hostname' => '192.168.1.101',
    'username' => 'read_user',
    'password' => 'read_pass',
],
'write' => [
    'hostname' => '192.168.1.100',
    'username' => 'write_user',
    'password' => 'write_pass',
],

框架会从read中随机挑一个从库执行查询，从write中挑主库执行写入。需要注意：从库同步延迟会导致刚写入的数据立刻读不到，如果业务对实时性要求高，可以用Db::name('user')->master(true)->find()强制走主库，根据行业经验，读写分离后必须把慢查询日志打开，因为从库索引没建好时，延迟会被放大。

调试和性能优化：配置之外的隐性参数

除了基本连接,database.php里还有几个参数直接影响性能。

• 'params' => [PDO::ATTR_TIMEOUT => 3]：连接超时设为3秒，避免数据库不可用时请求挂死。
• 'break_reconnect' => true：允许断线重连，后台脚本长跑时，MySQL的wait_timeout默认8小时会断掉空闲连接，开启这个能自动重连，但注意它只能重连不能保证事务回滚，事务中谨慎使用。
• 'fields_strict' => false：关闭字段严格校验，避免写入个别表时因字段不存在报错，但别全局关，有的表字段写错查不出来。

如何判断你的配置是否高效

用php think optimize:config生成生产环境配置缓存，能减少每次请求解析配置的开销，再用php think make:validate为数据库模型创建验证器，减少因为无效数据触发的SQL异常。真正影响查询速度的不是配置文件的长短，而是SQL本身，建议开启MySQL的慢查询日志：在my.cnf中设置slow_query_log=1和long_query_time=2，然后根据慢查询修改索引。

配置安全管理：别把密码写进代码

写进config/database.php的密码是明文，一旦代码仓库泄露全完蛋，正确做法是把敏感信息放进.env，并且让.env保持在版本库之外，具体操作：

1. 复制.env.example为.env，填入真实数据库信息。
2. 在.gitignore中添加/.env。
3. 在config/database.php中使用env()调用，不写明文默认值。

线上部署时,用宝塔面板或Github Actions注入环境变量，比如MYSQL_PASSWORD，然后配置文件写成：

'password' => env('database.password', '')

不设置默认值,强制从环境变量读取，把数据库权限收紧，应用账户只给SELECT、INSERT、UPDATE、DELETE，别给DROP或ALTER，这样就算配置泄露，影响也有限。

常见问题Q&A

Q：ThinkPHP 6和ThinkPHP 8的数据库配置有区别吗？

A：基本一致，都在config/database.php中使用env()函数，ThinkPHP 8强化了类型标注，部分驱动类名有调整，但配置键名完全兼容，升级时只需检查PHP版本是否满足8.1以上，以及数据库驱动是否扩展正确。

Q：为什么本地连接正常，服务器上就报”表不存在”？

A：通常是表前缀不一致，本地数据库表名是user，服务器上表名是tp_user，但配置里'prefix' => ''或反了，检查database.php和.env中的database.prefix，确保与服务器实际表名匹配，另外大小写敏感问题，Linux严格区分表名大小写，Windows不区分，建表时统一小写加下划线。

Q：连接池怎么配置？

A：ThinkPHP原生不提供连接池，需要借助Swoole或Workerman实现常驻内存，以Swoole为例，在server.php中开启pool选项，并设置connection_pool_size，然后数据库驱动使用think-swoole扩展包，但要注意，连接池中的连接不能用于事务，否则回滚无效，大多数中小项目没必要上连接池，开启PDO::ATTR_PERSISTENT常驻连接也能减少握手开销，但该参数在PHP-FPM下可能引发连接不稳定，建议先压测再决定。

配置数据库这件事,归根结底是理解框架的加载顺序和环境隔离，先把单库配置跑通，再谈多库和读写分离，多写日志、多打印config('database')，比盲目改代码有效得多，最后记住一句话：配置文件的每一处修改都先清理缓存，每一次连接异常都先看日志，这能让你少走很多弯路。