PHP cURL 怎样设置毫秒级请求超时

PHP cURL 的毫秒级请求超时，核心是同时设置 CURLOPT_CONNECTTIMEOUT_MS 和 CURLOPT_TIMEOUT_MS：前者限制建立连接的等待时间，后者限制整个 cURL 操作允许执行的最长时间。比如连接最多等 800 毫秒、整次请求最多等 1800 毫秒，就把这两个值作为整数毫秒传给 curl_setopt_array。

官方参考：https://www.php.net/manual/en/curl.constants.php

下面只讨论超时选项和返回错误，不把 HTTP 4xx/5xx 与 cURL 传输失败混为一谈。

先把两个毫秒选项分工清楚

CURLOPT_CONNECTTIMEOUT_MS只约束连接阶段；CURLOPT_TIMEOUT_MS约束一次 cURL 函数执行的总时长。总超时应该大于连接超时，否则连接预算还没用完，整个请求就可能先结束。

官方手册还提示：如果 cURL 使用系统名称解析器，连接中的解析部分仍可能采用整秒粒度，最小超时可能是一秒。毫秒配置代表预算单位更细，并不保证每个底层阶段都能精确到毫秒。

用整数毫秒配置一次请求

配置时建议把超时常量集中放在同一个数组里，避免调用链中途又覆盖选项。下面示例将连接上限设为 800 毫秒、总上限设为 1800 毫秒，并把响应内容与状态码分开处理。

 800,
    // 限制本次 cURL 操作的总时长，必须不小于连接预算。
    CURLOPT_TIMEOUT_MS => 1800,
    // 让 curl_exec 返回响应字符串，便于后续读取 HTTP 状态码。
    CURLOPT_RETURNTRANSFER => true,
]);

$body = curl_exec($handle);
$errno = curl_errno($handle);
$error = curl_error($handle);
$httpCode = (int) curl_getinfo($handle, CURLINFO_HTTP_CODE);

if ($body === false) {
    // 传输层失败时优先记录 cURL 错误码和文本，不把它当成 HTTP 状态码。
    error_log(sprintf('cURL failed: errno=%d message=%s', $errno, $error));
} elseif ($httpCode >= 400) {
    // 能收到 HTTP 响应，说明传输完成；4xx/5xx 属于服务端业务或协议结果。
    error_log(sprintf('HTTP request failed: status=%d', $httpCode));
} else {
    // 到这里才把响应正文交给业务层解析。
    echo $body;
}

curl_close($handle); // 释放当前句柄；PHP 8 中关闭函数不会强制销毁底层句柄。
?>

这里先判断 $body === false，再看 HTTP 状态码。这样可以区分“请求没有得到响应”和“请求得到了错误响应”两条路径；如果只检查状态码，连接超时等传输错误就容易被误判成状态码为 0 的业务失败。

超时返回时应该看什么错误

当 curl_exec 返回 false 时，用 curl_errno 保存数字错误码，用 curl_error 保存可读文本。毫秒上限触发后，错误文本通常会包含超时线索，但生产日志仍应保留目标主机、阶段和配置值，方便把连接超时与总传输超时区分开。

 500,
        CURLOPT_TIMEOUT_MS => 1500,
        CURLOPT_RETURNTRANSFER => true,
    ]);

    $body = curl_exec($handle);
    $result = [
        'ok' => $body !== false,
        'http_code' => (int) curl_getinfo($handle, CURLINFO_HTTP_CODE),
        'curl_errno' => curl_errno($handle),
        'curl_error' => curl_error($handle),
        'body' => $body === false ? null : $body,
    ];
    curl_close($handle); // 无论成功或失败，都释放本次请求句柄。

    return $result;
}
?>

上层可以先判断 ok，再按 curl_errno 做重试或降级；只有 ok 为真时，才根据 http_code 判断服务端返回是否可接受。不要把“把总超时调大”当作所有错误的解决方案，连接地址、DNS、证书、代理和服务端响应都可能是独立问题。

从秒级选项迁移到毫秒级时检查三件事

1. 不要混淆单位：CURLOPT_TIMEOUT 和 CURLOPT_CONNECTTIMEOUT 用秒；带 _MS 的对应选项用毫秒，传入的整数不要再乘一次 1000。
2. 保留连接预算：如果只设置 CURLOPT_TIMEOUT_MS，连接阶段会和后续收发共享总预算；需要单独限制连接时，再补上 CURLOPT_CONNECTTIMEOUT_MS。
3. 记录环境边界：确认 PHP cURL 扩展和底层 libcurl 支持这些常量；对系统名称解析器的整秒粒度保持预期，不把毫秒参数理解成每一层都能精确打断。

最终可以把这组规则压缩成一句话：连接上限解决“连不上时等多久”，总上限解决“整次请求最多占用多久”，curl_errno 负责说明传输为什么失败，HTTP 状态码负责说明服务端返回了什么。

常见追问

只设置 CURLOPT_TIMEOUT_MS 可以吗？

可以。它会为整次 cURL 操作提供总预算；如果还需要限制连接阶段，就再设置 CURLOPT_CONNECTTIMEOUT_MS。

HTTP 504 等于 cURL 超时吗？

不等于。504 是已经收到的 HTTP 响应；cURL 超时通常表现为 curl_exec 返回 false，应读取错误码和错误文本。