curl_error() 与 curl_errno() 调试共享失败问题的技巧

在使用 PHP 的 cURL 库进行网络请求时，curl_share_init() 函数用于初始化一个共享句柄（share handle），以便多个 cURL 会话（curl handle）共享资源，如 DNS 缓存、Cookie 等。这在高并发环境下有助于节省资源、提高效率。然而，很多开发者在使用 curl_share_init() 时可能会遇到共享失败的问题，这往往与资源冲突、错误配置或底层库（libcurl）的问题有关。

本文将带你了解如何通过 curl_error() 和 curl_errno() 这两个调试利器定位和解决 curl_share_init 带来的共享失败问题。

1?? 什么是 curl_share_init()？

curl_share_init() 用于创建一个共享句柄，通常与 curl_share_setopt() 配合使用来定义要共享的资源类型。最后，需要用 curl_share_close() 释放句柄。

简单示例：

$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

但是，如果配置或使用错误，某些共享操作可能会失败，表现为请求异常、数据错乱、甚至崩溃。

2?? 共享失败的常见原因

常见的失败原因包括：

• 在不同线程中使用同一个 cURL handle；

• 重复释放共享句柄或 handle；

• 设置的共享类型（如 COOKIE、DNS）在底层不支持；

• libcurl 版本不兼容。

要定位具体的错误，我们就需要用到 curl_error() 和 curl_errno()。

3?? curl_error() 和 curl_errno() 的调试技巧

这两个函数是 cURL 错误调试的核心：

• curl_error($ch) 返回最近一次 cURL 操作的错误信息（字符串形式）；

• curl_errno($ch) 返回最近一次 cURL 操作的错误代码（数字形式）。

它们通常配合使用：

$ch = curl_init('https://m66.net/api/test');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);

if ($result === false) {
    echo 'cURL Error Code: ' . curl_errno($ch) . "\n";
    echo 'cURL Error Message: ' . curl_error($ch) . "\n";
} else {
    echo 'Request successful: ' . $result;
}

curl_close($ch);

对于共享句柄：

$sh = curl_share_init();
if ($sh === false) {
    die("Failed to initialize curl share handle.\n");
}

$setopt_result = curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
if ($setopt_result === false) {
    echo "Failed to set share option.\n";
}

$ch = curl_init('https://m66.net/api/test');
curl_setopt($ch, CURLOPT_SHARE, $sh);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);

if ($result === false) {
    echo 'cURL Error Code: ' . curl_errno($ch) . "\n";
    echo 'cURL Error Message: ' . curl_error($ch) . "\n";
} else {
    echo 'Request successful: ' . $result;
}

curl_close($ch);
curl_share_close($sh);

4?? 常见错误代码及排查思路

对于 CURLE_SHARE_IN_USE，意味着当前共享句柄正被另一个句柄使用，不能同时配置或释放，需要检查代码逻辑。

5?? 实战排查步骤

1?? 确认 libcurl 版本支持
可以用 curl_version() 检查当前支持的特性。

2?? 分离问题范围
先用单个 cURL handle 测试，再引入共享句柄，确认是 share 相关引起的问题。

3?? 用 curl_error() 和 curl_errno() 获取详细错误
务必在 curl_exec() 后立即检查。

4?? 开启详细日志
通过 CURLOPT_VERBOSE：

curl_setopt($ch, CURLOPT_VERBOSE, true);

5?? 检查线程安全
不要在多线程中共享句柄，除非 libcurl 是线程安全编译。