PHP cURL multi 并发请求控制连接数的参数方法

批量调用接口时，真正需要限制的通常不是“同时创建多少个 easy handle”，而是 libcurl 此刻允许建立多少条连接。PHP cURL multi 可以在 multi handle 上分别设置总连接数和单主机连接数：前者保护本机和出口，后者避免某一个上游被瞬间打满。CURLMOPT_MAXCONNECTS 只负责连接缓存，不能替代并发限制。

官方地址：https://www.php.net/manual/en/function.curl-multi-setopt.php

libcurl 选项说明：https://curl.se/libcurl/c/curl_multi_setopt.html

先分清三个“连接数”

一次请求批次里可能有很多 easy handle，但它们不一定都在建立 TCP/TLS 连接。连接控制至少有三层：

因此，配置总量为 12、单主机为 4 时，三个域名可以共享最多 12 条活动连接，但同一域名最多占 4 条。若只设置 MAXCONNECTS=4，得到的是缓存淘汰策略，不是“最多四个请求同时跑”。

在 multi handle 上设置可解释的连接预算

连接限制属于 multi handle 级别，应该在加入 easy handle 之前设置。下面的示例保留一个完整的最小执行骨架：它把总连接数设为 12，把单主机连接数设为 4，并把缓存上限也设为 12。缓存值只是让已建立连接有足够位置复用，不能理解成第三个并发闸门。

 12,
    // 防止同一个上游独占全部连接预算。
    CURLMOPT_MAX_HOST_CONNECTIONS => 4,
    // 这是复用连接缓存容量，不是活动并发数。
    CURLMOPT_MAXCONNECTS => 12,
];

foreach ($limits as $option => $value) {
    // 设置失败要立即暴露，避免以为限流已经生效。
    if (!curl_multi_setopt($multi, $option, $value)) {
        curl_multi_close($multi);
        throw new RuntimeException('multi 连接参数设置失败');
    }
}

// 句柄可以先全部排队，活动连接由 multi 的限制调度。
$urls = [
    'https://api.example.test/a',
    'https://api.example.test/b',
    'https://files.example.test/c',
];
$handles = [];
foreach ($urls as $url) {
    $handle = curl_init($url);
    curl_setopt_array($handle, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 3,
        CURLOPT_TIMEOUT => 10,
    ]);
    curl_multi_add_handle($multi, $handle);
    $handles[] = $handle;
}

$running = 0;
do {
    // 反复驱动 multi，直到当前批次不再有活动传输。
    do {
        $status = curl_multi_exec($multi, $running);
    } while ($status === CURLM_CALL_MULTI_PERFORM);

    if ($status !== CURLM_OK) {
        throw new RuntimeException('multi 执行失败：' . $status);
    }
    if ($running > 0) {
        // 没有事件时短暂等待，避免忙轮询占满 CPU。
        curl_multi_select($multi, 1.0);
    }
} while ($running > 0);

foreach ($handles as $handle) {
    // 读取结果后移除并关闭 easy handle，避免句柄和连接状态泄漏。
    $body = curl_multi_getcontent($handle);
    curl_multi_remove_handle($multi, $handle);
    curl_close($handle);
}
curl_multi_close($multi);

这里的 example.test 只是文档示例域名，不能当作真实接口。生产代码还应通过 curl_multi_info_read() 逐个读取完成消息和错误码，而不是只依赖循环结束；否则某个请求的 HTTP 错误、DNS 错误或超时会被吞掉。

为什么设置了上限，吞吐仍可能不稳定

连接上限只限定 libcurl 的资源调度，不会保证每个请求都按固定顺序启动，也不会替应用层限制请求总数。常见的复盘顺序是：

1. 先记录每个 easy handle 的 URL 主机、开始时间、完成时间和 curl_errno()。
2. 确认是否真的有多个主机；只有一个主机时，MAX_HOST_CONNECTIONS 才是主要闸门。
3. 把连接超时和总超时分开设置，避免连接排队时无限等待。
4. 处理 curl_multi_select() 返回负值的情况，必要时短暂让出 CPU 后再驱动循环。

如果上游返回 429 或 503，不要只把总连接数继续调大。更稳的处理是降低单主机上限、加入应用层批次大小和退避重试，并把“排队时间”和“网络耗时”分别记录下来。

版本与 HTTP/2 边界要单独判断

PHP 手册列出的 CURLMOPT_MAX_TOTAL_CONNECTIONS 和 CURLMOPT_MAX_HOST_CONNECTIONS 从 PHP 7.0.7 起可用；CURLMOPT_MAX_CONCURRENT_STREAMS 从 PHP 8.2.0 起提供，用于 HTTP/2 连接上的并发流。HTTP/2 下“一条连接”和“多个流”不是同一个数量，不能把流上限直接换算成 TCP 连接上限。

上线前可以用 defined() 检查可选常量，并将最终生效的配置写入启动日志。兼容旧环境时，宁可明确降级为应用层批次控制，也不要静默假设某个 multi 选项已经存在。

常见问题

把 CURLMOPT_MAXCONNECTS 调小能限制并发吗？

不能。它控制连接缓存容量；活动连接限制应使用总连接数和单主机连接数参数。

所有 URL 都加入 multi 队列会不会立刻建立同样多的连接？

不会。easy handle 数量和活动连接数量是两件事，libcurl 会在 multi 级别按连接限制调度，但应用仍应控制批次规模和超时。

HTTP/2 只设置 MAX_HOST_CONNECTIONS 就够了吗？

不一定。还要看单连接上的并发流、上游限制和客户端版本；PHP 8.2 以上可进一步评估 CURLMOPT_MAX_CONCURRENT_STREAMS。