ThinkPHP6数据库端口配置与修改连接端口号详细教程

在ThinkPHP6里配置数据库端口，这事儿说简单也简单，但一个不留神，就可能掉进几个“坑”里。很多开发者习惯性地在配置里写 port，结果发现连接死活不走自己指定的端口，还是默认的3306。问题出在哪？关键就在于框架的字段名是固定的。

config/database.php 里配 hostport，不是 port

ThinkPHP6的数据库连接配置，其端口字段名是固定的 hostport。这跟标准PDO的参数名 port 或者其他一些框架的写法不一样。如果你写成 'port' => 3307，框架会直接忽略这个配置，连接依然会使用默认的3306端口。

正确的做法，是在 config/database.php 文件里，找到对应的数据库连接数组（比如 connections.mysql），然后加上这一行：

'hostport' => 3307,

这里有个细节需要注意：值应该是整数类型，别写成字符串 '3307'。除此之外，还有几个常见的配置失误点：

• 复制代码时，不小心带上了多余的空格或者中文标点。
• 把配置项写错了层级，比如写在了 connections 这个数组的外面，而不是具体的某个数据库连接配置内部。
• 项目使用了多环境配置（例如有单独的 database_dev.php），但当前运行的环境并没有正确加载这个配置文件。

.env 文件配 DB_PORT，但必须确认 Config::loadEnv() 已执行

通过环境变量文件 .env 来配置端口也是个好习惯，比如写上 DB_PORT=3307。但是，ThinkPHP6并不会自动加载 .env 文件，你必须确保 think\facade\Config::loadEnv() 这个方法被执行过。

在标准的项目结构中，这个方法通常在 base.php 或者入口文件里已经调用了。不过，如果你自定义了项目的启动流程，就有可能漏掉这一步。

怎么验证呢？很简单，在控制器里临时打印一下配置值：echo config('database.connections.mysql.hostport');。如果输出是 3307，那就没问题；如果还是 null 或者 3306，那就说明 .env 的配置没有生效，首要任务就是去检查环境变量的加载时机。

Db::connect() 动态连接时，hostport 必须显式传入

当你使用 Db::connect() 方法进行动态数据库连接时，需要格外小心。这种方式会绕过全局配置的合并逻辑，意味着你必须提供完整的连接参数。哪怕只缺少一个必要的键，框架就会用默认连接的配置来补全，这很可能导致你的端口设置失效。

看看下面这段代码，意图是只改端口，但实际上它不会起作用：

Db::connect(['hostname' => '127.0.0.1', 'database' => 'test', 'hostport' => 3307]);

原因就在于，它缺少了 type、username、password 这些同样是必需的参数。框架会用默认连接来补全这些缺失项，而默认连接里的 hostport 很可能是空的，最终连接还是会落到3306端口上。

正确的做法是，把所有必要的参数一次性给全：

• 'type' => 'mysql'
• 'hostname' => '127.0.0.1'
• 'database' => 'test'
• 'username' => 'root'
• 'password' => ''
• 'hostport' => 3307

记住，漏掉其中任何一个，都可能让端口的配置功亏一篑。

验证端口是否真起作用，别只看配置打印

最后，也是最关键的一步：验证。仅仅在代码里打印出配置数组显示有 hostport，并不代表PDO连接真的使用了这个端口。最可靠的验证方法，是直接查看连接日志里的DSN字符串，或者通过网络抓包观察TCP连接的目标端口。

一个实用的方法是开启数据库调试日志。在 config/database.php 中设置 'debug' => true，然后执行一次简单的查询操作。接着，去 runtime/log/ 目录下找到对应的SQL日志文件，搜索“DSN”关键字。你会看到类似这样的真实连接字符串：

mysql:host=127.0.0.1;port=3307;dbname=test

如果这里显示的是 port=3306，那毫无疑问，你的配置没生效。如果程序报错提示类似“Connection refused (111) on 127.0.0.1:3306”，那基本可以断定，连接尝试的仍然是默认的3306端口，配置根本没被应用。

还有一个容易忽略的点：不同数据库的默认端口是不同的。MySQL默认是3306，SQL Server是1433，PostgreSQL是5432。如果项目里混用了不同类型的数据库，却套用了同一套配置模板，这也是一个高频的翻车点。配置时，一定要对号入座。