php连接mysql带端口怎么设置？附完整连接代码

一、连接协议与端口生效原理：为什么不能写 localhost

在排查 PHP 数据库端口问题时，最常见的现象是：明明代码里已经指定了端口号 3307，但报错信息依然提示连接默认的 3306 失败，或者提示找不到本地套接字文件 mysql.sock。这与 PHP 底层数据库驱动对主机名的识别机制密切相关。

在 Linux 和类 Unix 操作系统中，当客户端程序将数据库主机名设置为 localhost 时，MySQL 客户端驱动会自动识别为本地进程通信，直接绕过整个 TCP/IP 网络协议栈，转而尝试通过本地 UNIX Domain Socket 文件进行连接。在这种模式下，你在代码中配置的任何 port 端口参数都会被底层驱动直接忽略。

只有当主机名明确设置为 127.0.0.1（即 IPv4 本地回环地址）或服务器的具体 IP/域名时，PHP 驱动才会真正启用 TCP/IP 协议栈建立套接字握手，此时指定的端口号参数才会精准生效。

二、标准配置与操作实施四步法

在实际工程环境中，修改或配置数据库端口不仅仅是在代码里加一个数字，而需要遵循端到端的验证流程，确保服务监听、网络通路、应用代码与异常控制全部闭环。

三、方法一：使用 PDO 连接带端口 MySQL（推荐方式）

PDO（PHP Data Objects）是现代 PHP 开发中连接关系型数据库的标准扩展。它具备统一的面向对象接口，支持安全的预处理语句，并且在连接配置上更加规范。

在使用 PDO 连接 MySQL 时，所有连接目标信息均被组织在数据源名称（DSN，Data Source Name）字符串中。设置自定义端口时，只需在 DSN 字符串中加入 port=端口号; 即可。

PDO 完整连接代码示例

 PDO::ERRMODE_EXCEPTION,
    // 默认结果集为关联数组
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    // 禁用模拟预处理，启用数据库原生的真实预处理语句
    PDO::ATTR_EMULATE_PREPARES   => false,
    // 连接超时时间设置为 5 秒
    PDO::ATTR_TIMEOUT            => 5,
];

try {
    // 4. 创建 PDO 实例并建立物理连接
    $pdo = new PDO($dsn, $username, $password, $options);
    
    // 5. 执行一次轻量心跳查询验证连接状态
    $stmt = $pdo->query("SELECT 1 AS connected, CURRENT_TIMESTAMP() AS server_time");
    $result = $stmt->fetch();
    
    echo "【成功】PDO 连接指定端口数据库成功！\n";
    echo "服务端时间：" . $result['server_time'] . "\n";

} catch (PDOException $e) {
    // 6. 异常精准捕获与排查日志输出
    echo "【失败】数据库连接异常：\n";
    echo "错误代码：" . $e->getCode() . "\n";
    echo "详细信息：" . $e->getMessage() . "\n";
}

四、方法二：使用 mysqli 连接带端口 MySQL

如果维护的是遗留系统或专注于 MySQL 专属功能的项目，可能会采用 mysqli 扩展。与 PDO 将所有信息统一打包为 DSN 字符串不同，mysqli 的构造函数采用独立的位置参数传递方式。

1. mysqli 面向对象风格完整代码

set_charset('utf8mb4');

    // 执行状态测试查询
    $result = $mysqli->query("SELECT 1 AS status");
    $row = $result->fetch_assoc();

    echo "【成功】mysqli 面向对象连接自定义端口数据库成功！\n";

} catch (mysqli_sql_exception $e) {
    echo "【失败】mysqli 连接错误：\n";
    echo "错误编号：" . $e->getCode() . "\n";
    echo "错误消息：" . $e->getMessage() . "\n";
}

2. mysqli 面向过程风格完整代码

在维护早期代码库时，可能会看到 mysqli_connect 函数。其传参顺序与面向对象构造函数完全一致，端口号同样作为第 5 个参数传入：

常见语法误区： 不要在 $host 变量中写冒号连接端口（例如 $host = '127.0.0.1:3307'）。某些其他语言的库支持这种写法，但 PHP 原生 mysqli 扩展并不解析主机字符串中的端口冒号，直接拼接会导致 DNS 解析失败或主机名格式非法错误。必须将端口提取出来作为独立的整型参数传递。

五、核心要素与常见报错排查手册

为了保障带端口连接在生产环境中的长期稳定，开发者需要同时核对主机格式、端口参数、访问权限和字符集设置四项核心要素。当遇到连接错误时，可按照下表迅速定位并处理。

排查实操建议

1. 验证端口是否开放且允许远端握手： 在运行 PHP 的服务器终端中，执行端口连通性探测命令：

   # 使用 nc (netcat) 命令进行快速 TCP 探测
   nc -zv 127.0.0.1 3307
   
   # 或使用 telnet
   telnet 127.0.0.1 3307

   如果输出 Connection to 127.0.0.1 3307 port [tcp/*] succeeded!，说明网络层及端口监听正常；若卡住超时，需优先检查服务器防火墙及容器端口映射规则。
2. 检查 MySQL 用户的 Host 限制： 当通过 127.0.0.1 连接时，MySQL 服务端会判定连接来源为 127.0.0.1。若该数据库用户仅被赋予了 'user'@'localhost' 权限，也会出现 1045 拒绝访问错误。此时需要在 MySQL 控制台中执行授权：

   -- 允许从 127.0.0.1 访问
   CREATE USER 'db_user'@'127.0.0.1' IDENTIFIED BY 'Secret_Pass_123';
   GRANT ALL PRIVILEGES ON app_database.* TO 'db_user'@'127.0.0.1';
   FLUSH PRIVILEGES;

六、总结

PHP 连接带有自定义端口的 MySQL 数据库，关键在于两点：

• 主机标识：必须使用真实 IP（如 127.0.0.1 或外部实际 IP），坚决避免使用 localhost，强制底层驱动通过 TCP/IP 协议栈建立连接。
• 端口传递：PDO 扩展在 DSN 中以 port=xxxx 键值对形式声明；mysqli 扩展将整型端口号作为构造函数或 mysqli_connect 的第 5 个参数传递。

只要牢记协议路由机制并按照规范格式组织参数，即可稳妥支持多实例、容器化以及云端自定义端口的各类 MySQL 连接场景。