PHP 8.5 curl_share_init_persistent 怎样复用跨请求的连接共享句柄

如果 PHP 服务在多个请求中反复访问同一批上游主机，PHP 8.5 的 curl_share_init_persistent() 可以把指定的 cURL 共享句柄保留下来：后续请求使用相同的共享选项时，有机会复用已有的 DNS 和连接状态。它解决的是 cURL 共享数据的跨请求生命周期问题，不是把 PHP 请求改造成一个通用连接池。

官方地址：https://www.php.net/manual/en/function.curl-share-init-persistent.php

最小做法是：用非空的 CURL_LOCK_DATA_* 数组创建持久句柄，再把它通过 CURLOPT_SHARE 绑定到每个 cURL 传输句柄。Cookie 不能放进这个持久共享集合。

先区分普通共享句柄和持久共享句柄

curl_share_init() 创建的普通共享句柄只在当前 PHP 请求生命周期内存在；curl_share_init_persistent() 创建的句柄不会在请求结束时销毁。PHP 官方文档还说明：如果已经存在一组相同 share_options 的持久句柄，新的调用会复用这组共享状态。

因此，复用的关键不是“每次都拿到同一个 PHP 变量”，而是共享选项集合相同，并且这些选项确实适合跨请求共享。通常可以把 DNS 查找和连接状态放在一个共享边界内；请求 URL、请求头、响应体和业务身份仍然属于每次传输自身。

选择 share_options 并创建持久句柄

参数必须是非空数组，成员是 CURL_LOCK_DATA_* 常量。本文只选择 CURL_LOCK_DATA_DNS 和 CURL_LOCK_DATA_CONNECT，分别表达 DNS 查找共享和连接共享。空数组、未知值、非整数值会触发异常；CURL_LOCK_DATA_COOKIE 明确不允许用于持久句柄。

这里的持久句柄只表达“哪些 cURL 状态可以共享”，并不会替你设置超时、TLS 校验、请求方法或响应读取方式。业务请求仍需对每个传输句柄单独配置。

把句柄绑定到多个 cURL 请求

要让共享发挥作用，每个独立的 cURL 传输句柄都要设置 CURLOPT_SHARE。同一 PHP 请求中可以绑定多个传输句柄；在长生命周期 SAPI 中，后续请求再次用同样的选项创建持久句柄时，运行时才有机会接上之前的共享状态。

图片中的“共享边界”可以理解为状态的归属关系，而不是请求的执行顺序。持久句柄适合让多个请求共享连接相关状态；业务响应不能因为共享句柄而互相覆盖。

处理版本、SAPI 与异常边界

这个函数从 PHP 8.5.0 开始提供，并要求 cURL 扩展可用。它更适合 FPM、常驻 worker 或其他长生命周期 SAPI；在每个请求都新建并销毁进程的环境里，跨请求的收益会受生命周期影响，不能只凭函数名断言一定减少连接成本。

创建时要把异常当成配置错误处理，而不是把它当成网络重试。以下三类输入尤其需要提前排除：

• share_options 为空：抛出 ValueError。
• 出现未知常量或非整数：分别可能抛出 ValueError 或 TypeError。
• 包含 CURL_LOCK_DATA_COOKIE：抛出 ValueError，因为跨请求共享 Cookie 可能把不同用户的敏感状态混在一起。

同样要注意，连接复用并不等于跳过 TLS 校验、超时、HTTP 状态码检查或身份鉴权。共享的是 cURL 能安全管理的状态，授权信息仍然必须按请求和用户边界隔离。

用最小封装落地

如果应用有多个上游请求，可以把“创建共享句柄”和“执行单个请求”分开。这样调用方只传 URL 和必要的请求参数，不会在每个业务方法里重复配置共享选项。

share = curl_share_init_persistent([
            CURL_LOCK_DATA_DNS,
            CURL_LOCK_DATA_CONNECT,
        ]);
    }

    public function get(string $url): string
    {
        // URL 和响应仍然属于本次请求，只有共享句柄来自持久配置。
        $handle = curl_init($url);
        if ($handle === false) {
            throw new RuntimeException('无法初始化 cURL');
        }

        try {
            curl_setopt($handle, CURLOPT_SHARE, $this->share);
            curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($handle, CURLOPT_TIMEOUT, 5);
            $body = curl_exec($handle);
            if ($body === false) {
                throw new RuntimeException(curl_error($handle));
            }
            return $body;
        } finally {
            // 即使执行抛错也关闭当前传输，避免句柄泄漏。
            curl_close($handle);
        }
    }
}

这个封装没有隐藏 HTTP 状态码检查，也没有把 Cookie、Authorization 或响应缓存塞进共享对象。若应用需要并发请求，应在更高层使用多句柄或异步调度，并继续保持每个传输句柄的错误处理。

按场景选择是否启用

最终可以用一句话判断：如果需要的是跨请求复用 DNS 或连接相关状态，并且能够控制生命周期，就使用固定的非 Cookie 共享选项；如果需求涉及用户身份、响应缓存或通用连接池，就应在更高层单独设计。

相关问题

curl_share_init_persistent 和 curl_share_init 有什么区别？

前者创建的共享句柄不会在 PHP 请求结束时销毁，并可在共享选项相同的情况下被复用；后者是当前请求内的普通共享句柄。

为什么不能共享 CURL_LOCK_DATA_COOKIE？

因为持久 Cookie 可能跨越不同 PHP 请求和不同用户边界，官方文档将该选项列为禁止项，避免敏感 Cookie 被错误混合。

绑定了共享句柄就一定复用连接吗？

不一定。它提供可复用的共享边界，实际效果还受 SAPI 生命周期、上游主机、TLS、连接状态和 cURL 运行环境影响，仍应通过应用自己的指标判断。