PHP 通过 PDO 连接 MySQL 时，如果目标主机不可达、端口被防火墙丢弃，或者数据库实例刚好在重启，连接函数可能不会立即返回错误，而是进入漫长的系统默认 TCP 超时等待。这个等待过程有时可以达到 30 秒甚至更长。对一次 Web 请求而言，数据库连接只是链路中的一环，但这一环如果缺少明确的超时控制，就会变成整个接口的阻塞点。
一、PDO 连接超时的默认行为与风险
new PDO() 在创建连接时，会通过底层驱动调用操作系统 socket 建立 TCP 连接。如果目标主机直接返回拒绝，错误很快就能被捕获；但如果目标主机不可达，例如内网 IP 不存在、防火墙直接丢弃 SYN 包，客户端就会按照操作系统的 TCP 重试策略反复发送连接请求。Linux 下 SYN 包的重试次数和间隔由内核参数 net.ipv4.tcp_syn_retries 等控制，整个过程可能持续几十秒甚至更久。
问题在于，PDO 自身在没有显式配置 PDO::ATTR_TIMEOUT 时，部分驱动并不会主动截断连接尝试，而是把超时完全交给操作系统。于是业务代码就会一直等待。对于 PHP-FPM 这类同步阻塞模型来说，每一个等待连接的工作进程都被占用，无法处理新的请求。并发稍微升高，连接池就会被打满，随后出现大量 504 或 502 错误。
更隐蔽的风险是，连接等待时间过长往往会让上游服务先超时。比如 Nginx 设置了 5 秒代理超时，但 PHP 后端还在等待 30 秒的数据库连接，最终后端执行结果已经没有意义。用户侧看到的是失败，但服务端资源仍然被无效占用，形成资源浪费和错误定位困难。
二、ATTR_TIMEOUT 的正确设置方式
PDO::ATTR_TIMEOUT 用于设置数据库连接阶段的超时时间，单位是秒，必须通过 PDO 构造函数的第四个参数 driver_options 数组传入。常见误区是把超时参数拼写在 DSN 字符串中，例如 mysql:host=db.internal;dbname=app;timeout=3。这种写法在 PDO MySQL 驱动中并不能稳定生效，无法作为可靠的超时控制手段。
// 错误：把超时写在 DSN 中，PDO MySQL 驱动不一定识别
$dsn = 'mysql:host=db.internal;dbname=app;timeout=3';
// 正确：通过构造函数的第四个参数传递
$options = [
PDO::ATTR_TIMEOUT => 3,
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
];
$pdo = new PDO('mysql:host=db.internal;dbname=app', 'user', 'pass', $options);
推荐同时设置 PDO::ATTR_ERRMODE 为 PDO::ERRMODE_EXCEPTION。这样一旦连接超时，PDO 会抛出 PDOException，开发者可以在 catch 块中记录日志、返回统一错误响应，或者触发降级逻辑。超时时间并非越短越好，生产环境通常可以设置为 2 到 5 秒，具体取决于网络环境与数据库位置。
还需要注意，PDO::ATTR_TIMEOUT 只作用于连接建立阶段。查询执行过程中的长时间等待，比如一条慢 SQL 执行 20 秒，并不受该参数控制。对于查询超时，需要结合 MySQL 的 MAX_EXECUTION_TIME 或应用层封装来实现。
三、ATTR_TIMEOUT 与 connect_timeout、wait_timeout 的区别
这三个参数名字相近，但作用层次完全不同。PDO::ATTR_TIMEOUT 是客户端在发起连接时的最大等待时间，它由 PHP 进程在连接阶段主动控制。即使 MySQL 服务器完全不可达，只要超过设定秒数，客户端就会中断连接并抛出异常。
MySQL 服务端的 connect_timeout 变量，是指服务器等待客户端完成连接握手包的时间。如果客户端连接很慢但服务器并没有宕机，该参数可能会产生影响。它默认是 10 秒，与 PHP 客户端设置无关。服务端超时会导致客户端收到连接被关闭的错误，但客户端无法主动控制这个服务端行为。
wait_timeout 和 interactive_timeout 则完全是另一个阶段的概念。它们控制的是已经建立好的空闲连接在多长时间后会被服务器主动断开，默认通常为 28800 秒。连接池中的连接被服务端关闭后，客户端下一次使用该连接时可能触发重连，而重连阶段的超时仍然由 PDO::ATTR_TIMEOUT 决定。
因此，不能希望用 MySQL 配置代替客户端超时，反之亦然。一个稳健的数据库访问层需要在客户端、服务端和连接池三个层面都设置合理的超时与保活策略。
四、快速失败机制在工程中的价值
快速失败是分布式系统设计中的重要原则。当数据库不可用时，接口尽快返回明确错误，比长时间挂起更有利于系统稳定。超时配置就是快速失败的第一道门槛。PDO::ATTR_TIMEOUT 让连接阶段有了确定的时间上界，避免请求无限期等待。
例如在数据库发生故障时，未设置超时的接口可能需要 30 秒才返回错误，此时网关已经超时，用户也早已离开。而设置 3 秒超时后，接口在 3 秒内即可返回 503 状态，监控系统立即报警，负载均衡器可以把流量摘除或触发熔断。对比之下，快速失败能显著降低雪崩风险。
function createDatabaseConnection(array $config): PDO
{
$dsn = sprintf(
'mysql:host=%s;port=%d;dbname=%s;charset=utf8mb4',
$config['host'],
$config['port'],
$config['database']
);
$options = [
PDO::ATTR_TIMEOUT => $config['connect_timeout'] ?? 3,
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
];
try {
return new PDO($dsn, $config['username'], $config['password'], $options);
} catch (PDOException $e) {
error_log('Database connection timeout: ' . $e->getMessage());
throw new RuntimeException('Database temporarily unavailable', 503, $e);
}
}
上面的封装将连接超时作为配置项统一管理，并在连接失败时抛出业务层可识别的运行时异常。这样上层框架可以根据异常类型返回降级数据或快速返回错误响应，而不是让整个请求堆在连接函数上。
五、常见误区与兼容性说明
并不是所有 PDO 驱动都完整支持 PDO::ATTR_TIMEOUT。PDO MySQL 驱动在连接阶段可以使用该属性，但某些老版本或有特殊构建的驱动可能存在行为差异。对于 SQL Server 数据库，使用 PDO_SQLSRV 时通常需要设置驱动专用的连接超时属性，而不是直接依赖 PDO::ATTR_TIMEOUT。开发前应查阅当前驱动文档。
另一个常见误区是，在连接已经建立之后通过 setAttribute() 修改 PDO::ATTR_TIMEOUT 并期望影响后续行为。ATTR_TIMEOUT 是连接阶段的配置项，必须在构造函数中传入，连接建立后再修改不会对当前连接生效，也无法缩短后续重连的超时时间。
还有开发者认为只要设置了 PDO::ERRMODE_EXCEPTION，连接超时就会立即抛出异常。实际上异常模式只决定错误如何被报告，并不会主动缩短连接等待时间。只有同时设置 PDO::ATTR_TIMEOUT，才能让连接阶段真正快速失败。两者配合使用，才能获得可靠的超时控制和干净的异常处理流程。
PDOATTR_TIMEOUT数据库连接超时修改时间：2026-08-26 15:46:28