PHP curl_error 函数
最后修改日期：2025 年 4 月 11 日
PHP curl_error 函数返回一个包含当前 cURL 会话最后错误的字符串。对于调试失败的 cURL 请求至关重要。该函数在 cURL 操作失败时提供人类可读的错误消息。
基本定义
curl_error 函数从 cURL 会话中检索最后一个错误消息。它返回一个纯文本错误消息，如果没有发生错误则返回一个空字符串。该函数以 cURL 句柄作为其唯一参数。
语法：curl_error(CurlHandle $handle): string。始终在 cURL 操作失败后调用此函数。它比仅检查 curl_exec 的 FALSE 值提供更多详细信息。
基本错误处理
此示例演示了在请求由于 URL 无效而失败时使用 curl_error 的基本错误处理。
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://nonexistent.example.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
此代码尝试连接到不存在的域。当 curl_exec 失败时，我们使用 curl_error 获取具体的错误消息。错误可能指示 DNS 解析失败或连接超时。
HTTP 状态码错误处理
此示例展示了如何将 curl_error 与 HTTP 状态码检查结合使用。
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://httpbin.org/status/404");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FAILONERROR, true);
$response = curl_exec($ch);
if ($response === false) {
$error = curl_error($ch);
$errno = curl_errno($ch);
echo "Error ($errno): $error";
} else {
echo "Response: " . $response;
}
curl_close($ch);
我们请求一个 404 状态码的端点，并将 CURLOPT_FAILONERROR 设置为将 HTTP 错误视为 cURL 错误。我们获取错误消息和错误编号以进行更好的调试。这有助于区分不同类型的故障。
超时错误处理
此示例演示了如何处理 curl_error 的超时错误。
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://httpbin.org/delay/10");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 2);
$response = curl_exec($ch);
if ($response === false) {
echo "cURL Error: " . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
我们为需要 10 秒的请求设置了较短的超时时间（2 秒）。当发生超时时，curl_exec 返回 FALSE。curl_error 提供了有关超时的详细信息。这对于检测缓慢或无响应的服务器很有用。
SSL 证书错误处理
此示例展示了如何处理 SSL 证书验证错误。
<?php
declare(strict_types=1);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://expired.badssl.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
$response = curl_exec($ch);
if ($response === false) {
echo "SSL Error: " . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
我们尝试连接到一个 SSL 证书已过期的站点。当启用 CURLOPT_SSL_VERIFYPEER 时，这会失败。curl_error 提供了有关 SSL 验证失败的详细信息。出于安全考虑，请始终在生产环境中验证 SSL 证书。
全面的错误处理
此示例演示了全面的错误处理和多重检查。
<?php
declare(strict_types=1);
function fetchUrl($url) {
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_SSL_VERIFYPEER => true
]);
$response = curl_exec($ch);
if ($response === false) {
$error = curl_error($ch);
$errno = curl_errno($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return "Request failed (HTTP $httpCode, cURL $errno): $error";
}
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode >= 400) {
return "HTTP Error $httpCode: " . $response;
}
return $response;
}
echo fetchUrl("https://httpbin.org/status/500");
这个全面的示例检查 cURL 错误、HTTP 状态码，并提供详细的错误信息。我们使用 curl_getinfo 来获取 HTTP 状态码，即使 curl_exec 失败。这种方法提供了最大的调试信息。
最佳实践
- 始终检查错误： 切勿假设 curl_exec 成功。
- 与 curl_errno 结合使用： 使用错误代码进行程序化处理。
- 记录错误： 记录错误以调试生产问题。
- 用户友好的消息： 为最终用户翻译技术性错误。
- 清理资源： 使用后务必关闭 cURL 句柄。
来源
本教程介绍了 PHP curl_error 函数，并通过实际示例展示了其在各种 cURL 错误处理场景中的用法。