PHP cURL 持久化 share handle 如何避免跨请求状态泄漏

PHP 8.5 引入 curl_share_init_persistent() 后，cURL 可以在长生命周期 SAPI 中跨请求复用一部分网络资源，但这不等于把整个 HTTP 会话做成公共缓存。安全的做法是只共享 DNS、连接和 TLS session，把 Cookie、Authorization、POST 数据以及业务 Header 留在当前请求的 easy handle 中。

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

持久化 share handle 的边界可以记成一句话：复用“怎么连服务器”，不要复用“当前用户是谁”。尤其不要把 CURL_LOCK_DATA_COOKIE 放进跨请求持久化集合。

持久化 share handle 该共享什么

curl_share_init_persistent() 接收一个非空的 CURL_LOCK_DATA_* 数组。数组决定哪些 libcurl 数据进入共享对象，而不是让所有 easy handle 自动共享一切。DNS 缓存能减少重复解析，连接池能减少重新建连，TLS session 可以降低再次握手的成本；这些数据本身不代表某个业务用户。

真正需要警惕的是 Cookie。PHP 手册直接把 CURL_LOCK_DATA_COOKIE 列为不允许的选项，因为跨 PHP 请求共享 Cookie 可能把一个用户的敏感会话带给另一个用户。即使业务接口看起来是“公共 API”，也不应该把 Cookie 当成连接复用的附带品。

最小配方：只建立无身份的持久化集合

下面的写法把持久化能力限制在网络层。CURL_LOCK_DATA_SSL_SESSION 是否加入，取决于你的连接模式和部署目标；不需要时可以删掉，先从最小集合开始。

这里没有调用 curl_share_setopt() 去修改持久化对象：PHP 8.5 的持久化函数在创建时就固定选项，并会按同一组选项复用对象。不要为了“方便”追加 Cookie，也不要把访问令牌写成 share handle 的全局属性；它们应由具体请求自己携带。

每个 easy handle 都要重新绑定请求身份

连接池和请求身份是两条线。每次调用都新建 easy handle，绑定同一个 share 对象，再单独设置认证头、Cookie 和业务参数。请求结束后释放 easy handle；持久化的是网络资源，不是这一轮的 Header。

function fetchPrivateResource(string $url, string $token): string
{
    $share = createPersistentShare();
    $ch = curl_init($url);
    if ($ch === false) {
        throw new RuntimeException('无法创建 cURL easy handle');
    }

    try {
        // 每次请求独立设置身份，Authorization 不进入共享对象。
        curl_setopt($ch, CURLOPT_SHARE, $share);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $token,
            'Accept: application/json',
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $body = curl_exec($ch);
        if ($body === false) {
            throw new RuntimeException(curl_error($ch));
        }
        return $body;
    } finally {
        // easy handle 只服务当前调用，释放引用，避免请求选项被下一次调用复用。
        unset($ch);
    }
}

如果业务真的需要 Cookie，要把 Cookie 的生命周期限定在当前请求，并按用户或会话明确管理；不要因为需要登录就改用持久化 Cookie share。认证 Header、请求体和自定义追踪标记同样如此。

版本和并发边界要单独处理

curl_share_init_persistent() 从 PHP 8.5 起可用，而且“持久化”依赖 SAPI worker 的生命周期；普通短生命周期执行方式不能简单假设它一定跨请求。兼容库应保留上面的 function_exists() 回退，或在最低 PHP 版本声明中明确要求 8.5。

另外，libcurl 不支持把共享连接在多个并发线程之间随意复用。PHP-FPM 多 worker 的情况通常是每个 worker 有自己的进程内状态；如果应用使用真正的多线程 SAPI，则要按 libcurl 的锁回调和连接共享限制重新设计，不要仅凭“persistent”字样判断线程安全。

相关问题

持久化 share handle 会自动共享 Cookie 吗？

不会。PHP 8.5 的 curl_share_init_persistent() 明确不接受 CURL_LOCK_DATA_COOKIE；这正是为了避免跨请求混合敏感 Cookie。

用了 CURLOPT_SHARE，还要每次新建 curl handle 吗？

建议新建。share handle 复用的是选定的网络资源，easy handle 上的 URL、Header、请求体和其他选项仍应按本次请求重新设置。

PHP-FPM 所有请求都会命中同一个持久化连接池吗？

不能这样假设。持久化对象的可见范围受 SAPI worker 生命周期影响，多 worker 还会分散到不同进程；它是优化手段，不是跨进程共享缓存。

发布前检查清单

• 持久化选项中没有 CURL_LOCK_DATA_COOKIE。
• Authorization、Cookie、POST 数据和业务 Header 没有写入共享对象。
• PHP 8.4 及以下有请求内回退，且没有在旧版本解析阶段引用不存在的持久化类型。
• 已按实际 SAPI、worker 数和并发模型验证连接复用收益，并把身份隔离作为必测项。