PHP cURL 连接超时和请求总超时怎么分别设置

PHP cURL 里，这两个参数要分工设置：CURLOPT_CONNECTTIMEOUT 只限制建立连接时愿意等待多久，CURLOPT_TIMEOUT 限制一次 cURL 执行允许消耗的总时间。比如连接最多等 3 秒、整个请求最多等 12 秒，可以同时设置为 3 和 12；总预算应大于连接预算，否则连接阶段还没走完就会先撞上总超时。

先把两个时间预算分开

CURLOPT_CONNECTTIMEOUT 的单位是秒，描述的是“尝试连接时等待的秒数”；设置为 0 表示不限制。CURLOPT_TIMEOUT 同样以秒为单位，但限制的是 cURL 函数执行的最大时间，默认值为 0，意味着传输阶段不会因为这个选项自动结束。两者不是并列的两段倒计时：连接时间属于总时间的一部分。

因此，常见的 API 调用可以采用“连接 3 秒、总计 12 秒”的预算。若域名解析、TCP 建连或 TLS 握手超过 3 秒，请求会尽快失败；如果连接已经成功，但服务端迟迟不返回完整响应，则由 12 秒的总上限兜底。

用一组配置把错误信息留下来

不要只判断 curl_exec() 返回值。开启 CURLOPT_RETURNTRANSFER 后，成功时可以取得响应体；失败时应立即读取错误码和错误文本，并在需要时记录 HTTP 状态码、总耗时和连接耗时。下面的示例把这些信息放在一个返回数组中，调用方可以决定重试还是降级。

 true,
        CURLOPT_CONNECTTIMEOUT => 3,
        CURLOPT_TIMEOUT => 12,
        CURLOPT_HTTPHEADER => ['Accept: application/json'],
    ]);

    // 执行请求；失败时不要把 false 当成空响应体。
    $body = curl_exec($ch);
    $errno = curl_errno($ch);
    $error = curl_error($ch);
    $info = curl_getinfo($ch);
    curl_close($ch); // 及时释放句柄，避免长驻进程累积资源。

    if ($body === false) {
        return [
            'ok' => false,
            'errno' => $errno,
            'error' => $error,
            'http_code' => (int) ($info['http_code'] ?? 0),
            'total_time' => (float) ($info['total_time'] ?? 0),
            'connect_time' => (float) ($info['connect_time'] ?? 0),
        ];
    }

    return [
        'ok' => true,
        'http_code' => (int) ($info['http_code'] ?? 0),
        'data' => json_decode($body, true),
        'total_time' => (float) ($info['total_time'] ?? 0),
        'connect_time' => (float) ($info['connect_time'] ?? 0),
    ];
}
?>

这里的超时失败通常会得到 cURL 错误码 28，但业务代码仍应以错误码和错误文本为准，不要把所有失败都归为“接口返回 500”。如果连接成功后收到 404 或 500，那是 HTTP 层结果，不是 cURL 连接超时。

需要毫秒时，明确切换单位

如果业务需要 500 毫秒的连接预算，可以使用 CURLOPT_CONNECTTIMEOUT_MS；整个请求需要 1500 毫秒则使用 CURLOPT_TIMEOUT_MS。同一类预算最好只选秒或毫秒的一套写法，避免后续维护者误读单位。PHP 手册还特别说明：当 cURL 使用标准系统 DNS 解析器时，连接解析部分仍可能按整秒粒度计时，极短的毫秒值不能保证把 DNS 阶段压到同样精细。

毫秒配置示例可以这样写：

 true,
    CURLOPT_CONNECTTIMEOUT_MS => 800,
    CURLOPT_TIMEOUT_MS => 2500,
]);

$body = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
curl_close($ch); // 无论成功失败都关闭句柄。

if ($body === false) {
    error_log("cURL failed: {$errno} {$error}"); // 记录错误码，便于区分超时。
}
?>

按请求类型安排总预算

内部健康检查通常可以给较短的连接和总预算；第三方接口要把 DNS、TLS、排队和响应时间一起考虑；下载大响应时，总超时不能简单照搬普通 JSON API 的数值。无论取值多少，都建议让连接上限小于总上限，并在日志中保留 URL 主机、错误码、HTTP 状态、连接耗时和总耗时，避免只留一句“请求失败”。

最后记住：超时参数只负责截止时间，不会替你决定是否重试。重试前要确认请求是否幂等，并给多次尝试设置更大的外层预算，否则每次 cURL 都成功等满 12 秒，反而会把接口拖得更慢。

常见问题

只设置 CURLOPT_TIMEOUT 可以吗？

可以，它能限制整次 cURL 执行时间；但无法单独表达“建连最多等多久”。对需要快速失败或区分网络故障的服务，建议同时设置连接上限。

CURLOPT_TIMEOUT 和 CURLOPT_TIMEOUT_MS 要一起设置吗？

不建议。它们表达的是同一类总时间预算，只是单位不同。选择一种单位并在配置旁写清楚，代码更不容易被误改。