PHP cURL家族完全指南：从核心函数到SSL排错与并发实践-平芜编程栈

在PHP圈子里，cURL是个绕不开的老伙计。凡是写过“抓取第三方接口”“模拟请求登录”“爬取页面数据”这类需求的，十有八九都用过它。说它是PHP的“瑞士军刀”一点不过分——HTTP请求、HTTPS加密、Cookie会话、文件上传下载、JSON接口对接，甚至并发请求，它都能扛。这篇文章围绕PHP函数cURL家族展开，把常用函数、关键参数、坑和排查思路一次性讲透，适合刚接触cURL的新手，也适合写了几年PHP、想更系统地补一补cURL细节的老手。

有人问，为什么不直接用file_get_contents？因为cURL是真正的“完整HTTP客户端”，能控制请求头、请求体、SSL证书校验、超时时间、代理、Cookie容器，还有一套独立的错误码体系。写完下面的内容你会发现，困扰你多时的“SSL握手失败”“403被拒”“返回空字符串”等问题，几乎都能在cURL家族里找到对应的开关。

1. 内容整体设计与思路拆解

1.1 为什么把cURL叫作“家族”

说它是家族，是因为PHP里跟cURL相关的不是孤零零一个函数，而是一整套配套API。最典型几个：

curl_init()：创建cURL会话，返回一个CurlHandle对象（老版本是资源类型）。
curl_setopt()/curl_setopt_array()：设置传输选项，这才是cURL的灵魂。
curl_exec()：执行请求，拿到结果。
curl_close()：关闭会话并释放资源。
curl_error()/curl_errno()：获取上一次请求的错误信息和错误码。
curl_getinfo()：获取请求的详细元信息，比如HTTP状态码、重定向次数、下载大小、SSL验证结果。
curl_multi_init()以及配套的curl_multi_add_handle()、curl_multi_exec()：实现并发请求，把多个独立请求“打包”在一个多路复用池里跑。

这组函数合起来就是一套完整的HTTP客户端工具链，所以业内习惯叫“cURL家族”。尤其是CurlHandle对象出现以后，cURL的写法比老式资源风格更顺手，curl_setopt_array()一次性批量设置选项，也让代码清爽不少。

1.2 cURL扩展的底层逻辑：从libcurl到PHP函数

PHP的cURL扩展本质上是一个“封装层”，真正的干活的是C语言库libcurl。这意味着你在PHP里设置的所有CURLOPT_*常量，最终都会被翻译成libcurl的参数，由libcurl去发起真实的网络请求。

这个底层逻辑决定了三个很重要的结论：

第一，curl_init()本身并不发起网络请求，它只是创建了一个“会话对象”，真正干活的是curl_exec()。所以你可以先花大量时间配置选项，再一次性执行。

第二，同一个CurlHandle可以多次执行。比如先GET一个页面，改一下CURLOPT_URL，再POST一次，依然有效，只要不curl_close()。

第三，PHP的cURL行为，跟你系统里安装的libcurl版本强相关。curl_version()能拿到当前PHP绑定的是哪个版本的libcurl以及支持的协议列表。如果遇到一些新出的特性（例如HTTP/2、某些TLS新选项）用不了，先查这个版本信息，往往答案就在里面。

1.3 cURL vs file_get_contents：选型分析

很多初学者都用过file_get_contents($url)来抓数据，它确实能跑通简单的GET请求。但一旦遇到以下场景，就得换cURL：

场景	file_get_contents	PHP cURL
自定义请求头	要靠`$http_response_header`变通，很别扭	`CURLOPT_HTTPHEADER`直接塞数组
POST + JSON body	需要配置`stream_context_create()`，麻烦	`CURLOPT_POST`+`CURLOPT_POSTFIELDS`，一行搞定
设置超时到毫秒级	固有时钟粒度不够	`CURLOPT_TIMEOUT_MS`支持毫秒
忽略SSL证书校验	改php.ini全局，影响所有代码	`CURLOPT_SSL_VERIFYPEER`定点控制
抓取后需要状态码	没有专门API，靠`$http_response_header`解析	`curl_getinfo($ch, CURLINFO_RESPONSE_CODE)`
并发请求	基本做不了	`curl_multi_*`可并行

所以我个人判断：小项目、单次GET、不关心状态码的时候，file_get_contents能用；但只要涉及接口对接、模拟登录、文件上传、多个请求同时发，请直接上cURL。它看着代码多一点，换来的是确定性和控制力。

2. 核心细节解析与实操要点

2.1 最常用的PHP cURL函数清单

把cURL家族整理成表，看起来更直观。这里我不打算贴手册，只挑日常开发里频率最高的那些：

函数	典型用途	注意点
`curl_init([string $url])`	创建会话，可选初始化URL	PHP 8.0后返回`CurlHandle`对象
`curl_setopt($ch, $option, $value)`	设置单个选项	常量名别写错，比如`CURLOPT_RETURNTRANSFER`常被少写一个R
`curl_setopt_array($ch, array $options)`	批量设置选项	减少多次调用开销，代码更清晰
`curl_exec($ch)`	执行请求	返回`false`表示失败；开启`CURLOPT_RETURNTRANSFER`后返回响应体
`curl_close($ch)`	关闭会话	PHP 8.0后对象会自动释放，显式关闭仍推荐
`curl_error($ch)`	获取错误信息	配合`curl_errno()`使用，错误号为0表示无错误
`curl_errno($ch)`	获取错误码	错误码不等于HTTP状态码，别混
`curl_getinfo($ch[, $option])`	获取请求信息	常用`CURLINFO_RESPONSE_CODE`,`CURLINFO_TOTAL_TIME`,`CURLINFO_EFFECTIVE_URL`
`curl_multi_init()`	创建并发处理句柄	并发请求必须要用它
`curl_reset($ch)`	重置会话所有选项	循环复用同一句柄时好用

这里有个容易被忽视的细节：curl_errno()返回的不是HTTP状态码。比如你请求了一个不存在的页面，HTTP返回404，curl_errno()仍然是0，因为TCP层面、TLS层面、HTTP传输都成功了，是服务器主动回了个404。要判断“请求是否成功”，你既看curl_errno() === 0，也要用curl_getinfo($ch, CURLINFO_RESPONSE_CODE)确认你期望的状态码。

2.2 关键参数详解：CURLOPT_*选项怎么选

CURLOPT_*常量非常多，手册里列了上百个。真正要烂熟于心的，我按用途分成几组：

传输与返回

CURLOPT_URL：目标URL。一般放在curl_init()里或执行前设置，但执行中重定向后会变成最终URL，你可以用curl_getinfo($ch, CURLINFO_EFFECTIVE_URL)看到真实地址。
CURLOPT_RETURNTRANSFER：是否把响应内容作为字符串返回。true就是“返回结果”，false则是直接输出到缓冲区。几乎所有封装库第一步都是设它为true，不然你很难拿到原始返回体。
CURLOPT_HEADER：设为true时，返回内容里包含响应头。抓包调试、需要解析Set-Cookie时很有用。
CURLOPT_NOBODY：只发HEAD请求，不取响应体，适合探测链接是否存在。
CURLOPT_FOLLOWLOCATION：跟随重定向，配合CURLOPT_MAXREDIRS限制最大跳转次数。
CURLOPT_AUTOREFERER：重定向时自动带上Referer头，某些站点会校验来源，这个开关能省事。

请求体与请求头

CURLOPT_POST：设为true表示POST请求。
CURLOPT_POSTFIELDS：POST数据。传字符串时按application/x-www-form-urlencoded发送；传数组时更灵活，能构造multipart/form-data，适合文件上传。一个常见坑：传数组时，PHP会为@/path/file这种老语法处理文件上传，但新版本更推荐用CURLFile对象。
CURLOPT_HTTPHEADER：数组形式的请求头，比如['Content-Type: application/json', 'Accept: application/json']。
CURLOPT_USERAGENT：设置User-Agent。很多服务端会校验UA，你不想被识别成脚本，就设成一个常见浏览器的UA。
CURLOPT_REFERER：模拟来源页面。
CURLOPT_COOKIE：直接设置Cookie请求头字符串，适合你已经手动拿到了cookie的情况。
CURLOPT_COOKIEJAR/CURLOPT_COOKIEFILE：把服务器返回的Set-Cookie保存到文件，或从文件读取Cookie，是模拟登录、保持会话的利器。

超时与连接

CURLOPT_TIMEOUT：整个请求允许的最大秒数。
CURLOPT_CONNECTTIMEOUT：连接阶段超时。这个很重要，否则目标机器不响应时，脚本可能挂很久。
CURLOPT_TIMEOUT_MS和CURLOPT_CONNECTTIMEOUT_MS：毫秒级版本，适合对耗时敏感的接口。
CURLOPT_DNS_CACHE_TIMEOUT：DNS缓存时间。

SSL/TLS

CURLOPT_SSL_VERIFYPEER：是否校验证书。开发环境临时调试可以设false，生产环境强烈建议保持true，否则等于裸奔。
CURLOPT_SSL_VERIFYHOST：是否校验主机名与证书CN/SAN匹配。常规设2表示必须校验。
CURLOPT_CAINFO：指定CA证书路径。公司内网自签名证书、或者系统CA库太旧的场景，这个选项能帮你绕过“证书不受信任”的报错，同时保留校验能力。
CURLOPT_SSLVERSION：指定TLS版本，比如CURL_SSLVERSION_TLSv1_2或CURL_SSLVERSION_TLSv1_3。

其他

CURLOPT_USERPWD：HTTP Basic认证的用户名密码，格式user:password。
CURLOPT_HTTPAUTH：配合CURLAUTH_BASIC、CURLAUTH_DIGEST等使用。
CURLOPT_ENCODING：设置Accept-Encoding: gzip，并自动解压，能省流量。
CURLOPT_PROXY：走代理请求，爬虫抓取、调试联调时会用。

2.3 错误获取与调试三件套：curl_error、curl_errno、curl_getinfo

cURL报错最让人头疼的地方在于，它经常“什么都不返回”。此时第一反应不应该是怀疑人生，而是把这三样掏出来：

$ch = curl_init('https://api.example.com/data'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, ]); $output = curl_exec($ch); if (curl_errno($ch)) { // 这是cURL层面的错误，比如超时、TLS握手失败、连接被拒 echo 'cURL错误号: ' . curl_errno($ch) . PHP_EOL; echo 'cURL错误信息: ' . curl_error($ch) . PHP_EOL; } else { // 这是HTTP层面的状态码，即使拿到200也不代表业务成功 $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); echo "HTTP状态码: {$status}" . PHP_EOL; // 顺便看下耗时和最终URL，排查重定向问题 echo "总耗时: " . curl_getinfo($ch, CURLINFO_TOTAL_TIME) . PHP_EOL; echo "最终URL: " . curl_getinfo($ch, CURLINFO_EFFECTIVE_URL) . PHP_EOL; } curl_close($ch);

这个模板是很推荐的。关键思维是“分层排查”：先看传输层是否成功，再看HTTP状态码是否符合预期，最后解析业务返回体。很多时候，cURL返回false而curl_error()却是空的，这种情况多半是超时长到像挂起，然后被系统中断，也可能是目标服务器主动断开了连接。

另外说一个我踩过多次的坑：curl_getinfo()必须在curl_exec()之后、curl_close()之前调用，否则拿不到值。PHP 8.0以后虽然CurlHandle在脚本结束才会释放，但你要是提前unset了，同样拿不到。

2.4 SSL相关选项：ssl_verifypeer、CA证书与TLS版本

SSL不是cURL独有的麻烦，但它在PHP里确实折腾过很多人。从热词里就能看到一堆跟“SSL routines”“certificate problem”相关的搜索。

核心要理解三件事：

第一，CURLOPT_SSL_VERIFYPEER到底校验什么。它校验的是对方服务器证书是否由一个受信任的CA签名、证书是否过期、证书链是否完整。系统里必须有一份CA根证书库，PHP才能完成校验。Windows环境下如果PHP的curl.cainfo配置没设置，或者OpenSSL找不到CA文件，就极其容易报出“certificate verify failed”这类错。

第二，CURLOPT_SSL_VERIFYHOST校验的是主机名。证书里写的是api.example.com，你请求的是api.example.com，匹配；如果你请求的是IP，证书按DNS name签发，那就会校验失败。这个开关大多数时候保持2即可。

第三，版本兼容问题。老libcurl不支持TLS 1.3，新服务器只支持TLS 1.2以上的时候，老版本可能握手失败。排查办法：curl_version()['ssl_version']看看OpenSSL版本；必要时显式指定CURLOPT_SSLVERSION。

生产环境如果真的遇到自签名证书、公司内网证书，推荐下载CA证书文件，然后设置CURLOPT_CAINFO指向该文件，而不是直接关掉校验。这样既避免中间人攻击风险，也能正常请求内网服务。

3. 实操过程与核心环节实现

3.1 基础GET请求与超时控制

先给一个可以“抄作业”的GET请求模板。假设要请求一个公开接口，返回JSON：

function http_get(string $url, array $headers = [], int $timeout = 10): array { $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => $timeout, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_FOLLOWLOCATION => true, CURLOPT_MAXREDIRS => 3, CURLOPT_USERAGENT => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) PHP-cURL/'.phpversion(), CURLOPT_ENCODING => 'gzip, deflate', ]); if ($headers) { curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); } $body = curl_exec($ch); $errno = curl_errno($ch); $error = curl_error($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch); if ($errno !== 0) { return ['ok' => false, 'errno' => $errno, 'error' => $error, 'status' => 0, 'body' => '']; } return ['ok' => true, 'errno' => 0, 'error' => '', 'status' => $status, 'body' => $body]; } $result = http_get('https://api.example.com/articles?page=1'); print_r($result);

几个要点：

CURLOPT_TIMEOUT设成10秒、连接超时5秒，是为了防止接口卡死拖垮整个脚本。如果你在写队列消费脚本，超时控制格外重要，建议把它做成参数，不同任务用不同的超时。
CURLOPT_FOLLOWLOCATION开启后，如果遇到301/302重定向，cURL会自动跳到最终地址。但要注意，某些重定向会丢失POST数据，遇到这种情况，需要检查CURLOPT_POST和CURLOPT_POSTFIELDS的重发逻辑。
CURLOPT_ENCODING => 'gzip, deflate'会自动带上Accept-Encoding并在获取响应体后解压，对抓取一些体积大的页面很有帮助。

3.2 POST提交、Cookie与模拟登录

POST是接口对接最常见的动作。JSON接口和表单接口的写法略不同。

JSON接口：

$ch = curl_init('https://api.example.com/login'); $payload = json_encode([ 'username' => 'demo', 'password' => 'secret', ], JSON_UNESCAPED_UNICODE); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Accept: application/json', 'Content-Length: ' . strlen($payload), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch);

表单接口，也就是传统application/x-www-form-urlencoded：

$ch = curl_init('https://example.com/login'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query([ 'username' => 'demo', 'password' => 'secret', 'remember' => 1, ]), ]); $body = curl_exec($ch); curl_close($ch);

注意：CURLOPT_POSTFIELDS如果传数组，PHP会把它转成multipart/form-data，对于普通表单登录，服务端可能解析不了；所以最好用http_build_query()转成字符串，强制使用application/x-www-form-urlencoded。这是一个容易被忽略但非常实用的细节。

模拟登录时，Cookie管理是关键。假设登录成功后服务器返回Set-Cookie，下一次带Cookie访问受保护页面：

$cookieFile = sys_get_temp_dir() . '/my_cookie.txt'; // 第一次请求：登录，并把Cookie写入文件 $ch = curl_init('https://example.com/login'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query(['username' => 'demo', 'password' => 'secret']), CURLOPT_COOKIEJAR => $cookieFile, ]); curl_exec($ch); curl_close($ch); // 第二次请求：读取Cookie文件，访问需要登录的页面 $ch = curl_init('https://example.com/profile'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_COOKIEFILE => $cookieFile, ]); $html = curl_exec($ch); curl_close($ch);

CURLOPT_COOKIEJAR负责把服务器返回的Cookie存进文件，CURLOPT_COOKIEFILE负责发送Cookie。两个搭配起来，就能在多个cURL会话之间维持登录态。这也是写“PHP充值卡密类网站”的抓单机器人、或对接第三方后台时的常见套路。

3.3 文件上传、下载与断点续传

PHP cURL做文件上传，关键是CURLFile对象。很多老代码还在用@/path/file，这在PHP 5.5之后被标记废弃，建议直接用CURLFile。

上传文件示例：

$ch = curl_init('https://api.example.com/upload'); $file = new CURLFile('/path/to/local.jpg', 'image/jpeg', 'photo.jpg'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => [ 'title' => '我的头像', 'file' => $file, ], CURLOPT_HTTPHEADER => ['Accept: application/json'], ]); $body = curl_exec($ch); curl_close($ch);

这里有个细节：CURLOPT_POSTFIELDS传数组时，其他字段都会被编码进multipart body，文件字段的值必须是CURLFile对象，否则不会被正确识别。

下载大文件时，除了直接拿返回字符串，还可以用CURLOPT_FILE把响应体写入文件流。配合CURLOPT_RANGE实现断点续传：

$fp = fopen('/path/to/save.zip', 'ab'); $ch = curl_init('https://example.com/bigfile.zip'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_FILE => $fp, CURLOPT_RANGE => 1048576 . '-', // 从第1MB开始下载 CURLOPT_FOLLOWLOCATION => true, ]); curl_exec($ch); curl_close($ch); fclose($fp);

CURLOPT_FILE会让cURL把响应体直接写入这个句柄，而不是返回字符串，对处理大文件非常友好，不会撑爆内存。CURLOPT_RANGE则让服务器返回指定字节范围，服务器支持的话就能续传。注意：CURLOPT_RANGE的生效依赖服务器支持Range请求头，不是所有下载接口都行。

3.4 用curl_multi_*实现并发请求

单个请求一个个发，在大批量场景里非常浪费时间。比如要调20个查询接口，每个耗时300ms，串行要6秒；用curl_multi_*并发，最慢那个决定总时长，体验完全不同。

curl_multi_init()并发的基本写法：

function http_multi_get(array $urls): array { $mh = curl_multi_init(); $handles = []; foreach ($urls as $key => $url) { $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_CONNECTTIMEOUT => 5, ]); curl_multi_add_handle($mh, $ch); $handles[$key] = $ch; } $running = null; do { $status = curl_multi_exec($mh, $running); if ($running) { curl_multi_select($mh, 0.5); // 等待至少一个socket有数据 } } while ($running > 0 && $status === CURLM_OK); $results = []; foreach ($handles as $key => $ch) { $results[$key] = curl_multi_getcontent($ch); curl_multi_remove_handle($mh, $ch); curl_close($ch); } curl_multi_close($mh); return $results; } $urls = [ 'a' => 'https://api.example.com/a', 'b' => 'https://api.example.com/b', 'c' => 'https://api.example.com/c', ]; $responses = http_multi_get($urls);

几个容易踩的点：

curl_multi_exec()第一次调用就会尝试启动所有请求，返回的第二个参数$running表示还有多少请求在执行。循环里必须调用它，直到变成0。
curl_multi_select()是阻塞等待至少一个连接有响应，但PHP手册里提到它可能在没有活动时提前返回，所以循环时别省略curl_multi_exec()的轮流检查。
每个子请求想单独拿HTTP状态码，可以在循环里用curl_getinfo($ch)，但要在curl_multi_remove_handle()之前做，否则句柄状态可能已经变了。
并发量不是越大越好。有些接口方有并发限制，建议加个信号量或分批并发，比如每批10个请求。

3.5 命令行cURL与PHP脚本协同

虽然这是PHP cURL主题，但命令行curl命令跟PHP里那套函数关系密切。调试时我经常先在终端里用curl -v看完整请求响应，确认没问题再抄到PHP里。热词里搜索“curl -v”的人很多，因为它就是终端调试的“放大镜”。

常见命令组合：

# 看完整HTTP报文（含请求头和响应头） curl -v https://api.example.com/items # 只看响应头 curl -I https://api.example.com/items # 带参数POST curl -X POST https://api.example.com/login -d 'username=demo&password=secret' # 发送JSON curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{"username":"demo","password":"secret"}' # 携带Cookie文件模拟登录后的请求 curl -b cookies.txt https://api.example.com/profile # 设置超时和UA curl -A "Mozilla/5.0" --max-time 10 https://api.example.com/items # 二进制文件下载，断点续传 curl -C - -o bigfile.zip https://example.com/bigfile.zip

命令行里curl -v输出的>行是请求头，<行是响应头，SSL connection using TLSv1.3这类信息能快速判断TLS握手出了什么问题。等到PHP那边报错的时候，先在命令行里复现一遍，常常能定位是请求本身的问题还是PHP配置的问题。我在日常排错中，几乎每次都会先跑一次命令行curl，把“是不是PHP封装的问题”跟“是不是服务器返回的异常”区分开。

3.6 cURL组合技：伪协议、序列化与JSON

PHP cURL不只是请求外部URL，也可以跟PHP内置的php://协议、序列化机制、JSON解析搭配使用，组成一些高效的小工具。

用php://input接收原始请求体

很多接口文档让你传原始JSON，用php://input读出来再json_decode，是标准做法。配合cURL发送请求时，代码要确保Content-Type设置正确，否则对方可能解析不了。比如上面JSON接口的例子，Content-Type: application/json是关键，漏掉这一行，服务端可能拿到$_POST为空。

JSON序列化和中文编码

用json_encode()时，我习惯加上JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES，避免中文被转成\uXXXX，避免URL里的/被转义。这样发给对方接口的数据可读性强，日志排查也更方便。

PHP序列化数据与接口对接

有些老接口不返回JSON，而是返回PHP序列化字符串，比如a:2:{s:4:"code";i:0;s:4:"data";...}。处理方式很简单：先curl_exec()拿到字符串，再unserialize()解析。但要注意：如果对方返回的数据末尾有多余空白字符，unserialize()会报错，可以先trim()一下。另外，序列化数据里的对象类型要求先定义对应类，否则只会得到__PHP_Incomplete_Class对象。这种场景不多，但遇到过一回就会觉得组合技值得掌握。

4. 常见问题与排查技巧实录

4.1 curl: (35) SSL routines: unexpected eof while reading

这是最近搜索量很大的一个错误。完整报错可能是：

curl: (35) error:0a000126:SSL routines::unexpected eof while reading

还有一个相近的：

error: rpc failed; curl 56 schannel: server closed abruptly (missing close_notify)

说人话就是：SSL/TLS握手或传输过程中，服务器连接在“正常关闭通知（close_notify）”之前就被掐断了。常见诱因：

服务器配置了TLS版本限制，客户端尝试的TLS版本不被支持。
服务器端的防火墙或WAF主动断开了TLS握手。
服务商对特定客户端指纹做了拦截。
旧版OpenSSL跟新版TLS协议不兼容，尤其是Windows下OpenSSL版本过低。

排查路径：

在命令行用curl -v连接目标地址，看握手阶段卡在哪。
检查本机OpenSSL版本和PHP编译时的SSL库版本是否过旧。php -i | grep -i openssl。
尝试显式指定TLS版本：curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);
如果目标是内网灰度环境，且你能确认证书本身没问题，可以临时设CURLOPT_SSL_VERIFYPEER => false验证是不是证书链的问题，但生产环境别这么干。

4.2 curl: (60) SSL certificate problem: unable to get local issuer certificate

这个错误看起来是“本地CA证书缺失”。Linux下经常是因为PHP的curl扩展没配置CA路径；Windows下经常是因为没安装CA bundle。

解决方案：

下载cacert.pem，在php.ini里配置curl.cainfo指向该文件。
或者在代码里指定：curl_setopt($ch, CURLOPT_CAINFO, '/path/to/cacert.pem');。
如果服务端证书是自签名或公司内部CA签发的，需要把该CA证书加入信任列表，或者用CURLOPT_CAINFO指向公司的根证书。

注意不要为了省事直接把CURLOPT_SSL_VERIFYPEER关闭，因为这会无声地放弃服务器身份校验，存在中间人攻击风险。临时调试可以，线上代码里出现这个选项，应该被视为警讯。

4.3 curl: (22) The requested URL returned error: 403

curl: (22)的意思是“服务器返回了非2xx开头的HTTP状态码”。403表示拒绝访问。

常见原因和对策：

服务器做了UA拦截：把CURLOPT_USERAGENT设成真实浏览器UA。
服务器校验Referer：加上CURLOPT_REFERER。
服务器对IP频率限制：考虑用代理池或加延时。此时命令行里可以加-x指定代理。
服务器要求Cookie或登录态：先用浏览器或curl -c拿Cookie，再在代码中带上。
有些CDN/防火墙会校验TLS指纹，cURL的TLS指纹太明显，可能被识别为爬虫。这种场景比较棘手，通常需要模拟浏览器的TLS指纹，PHP层面要配合第三方库（比如Guzzle + cURL参数调优）才能解决。

排错时不要只盯着错误码，先看响应体内容。403页面里往往有验证码、登录跳转、风控提示，这些才是解决问题的线索。用curl -v加上-H "User-Agent: ..."，多试几组头部组合。

4.4 curl: (23) Failure writing output to destination

这个错误一般发生在命令行下载场景，PHP里也可能在CURLOPT_FILE写文件时出现。意思是“磁盘写入失败”。最常见的是：

磁盘空间满了。
目标目录没有写权限。
fopen()返回的句柄已失效或位置不可写。
跨设备移动文件、NFS挂载目录不稳定。

处理办法：先df -h看磁盘空间，touch测试目录可写性，检查代码中fopen()是否成功了。如果是在管道中（比如curl ... | bash这类用法），还得注意管道另一端提前退出导致的写入失败。PHP里用CURLOPT_FILE时，建议先判断fopen()结果，别直接把false传给cURL。

4.5 curl_multi并发时结果全空或串行

用curl_multi_*时，很多人会写一个简单循环然后发现：怎么还是一个个返回的？原因是curl_multi_exec()只在第一次调用时真正发起请求，后续必须通过curl_multi_select()等待事件，然后继续调用curl_multi_exec()让libcurl处理已经完成的数据。如果你漏掉curl_multi_select()，或者循环条件写错，就可能退化成串行。

还有另一个诡异场景：并发10个请求，有2个总是返回空字符串。排查思路：

单独对这2个URL发一次普通请求，确认不是目标接口本身的问题。
检查CURLOPT_TIMEOUT是否过短，并发时每个请求的计时是独立的，但如果服务器连接池有限，等待排队的时间也算在超时里。
用curl_error($ch)在curl_multi_getcontent()之前看看有没有报错。

4.6 PHP接口返回“数组对象”和跨域JSONP问题

很多搜索词指向一个共性困惑：PHP接口返回的数据为什么前端拿到的是数组对象？为什么有时请求跨域失败？

先说“数组对象”：PHP的json_encode()把数组转成JSON时，如果数组键是连续的数字索引，会输出[1,2,3]这种数组；如果键是字符串，会输出{"a":1,"b":2}这种对象。前端说拿到“数组对象”，通常是因为服务端返回了对象结构。想控制输出形态，可以在json_encode()前对数据重新索引，或用array_values()强制转成列表。

再说跨域和JSONP。cURL发送的是服务端到服务端的请求，不存在浏览器同源策略问题。跨域问题是浏览器引入的。如果你用cURL请求接口正常，但浏览器的AJAX请求报跨域，说明需要在PHP响应头里加：

header('Access-Control-Allow-Origin: *'); header('Access-Control-Allow-Methods: GET, POST, OPTIONS'); header('Access-Control-Allow-Headers: Content-Type');

JSONP则是老式跨域方案：接口返回的不是JSON，而是callback({...})，前端通过<script>标签加载。PHP侧实现：

$callback = $_GET['callback'] ?? 'callback'; $data = ['code' => 0, 'msg' => 'ok']; echo $callback . '(' . json_encode($data) . ')';

注意$callback要做白名单校验，避免被注入恶意脚本。

4.7 常见问题速查表

现象	可能原因	处理建议
`curl_errno()`为28	请求超时	提高`CURLOPT_TIMEOUT`或检查目标是否可达
HTTP 403	UA/Referer/IP被限制	设置浏览器UA、Referer，加延时或代理
`curl: (60)`	本地CA证书缺失	配置`CURLOPT_CAINFO`或`curl.cainfo`
`curl: (35)`unexpected EOF	TLS协议不兼容或连接被中断	指定`CURLOPT_SSLVERSION`，检查TLS版本
返回false但无错误信息	超时被中断、目标静默断开	增加日志记录连接耗时，分层排查
并发请求串行	`curl_multi_*`循环写错	用前面的并发模板
上传文件用`@file`失效	PHP 5.5+废弃旧语法	改用`CURLFile`
中文乱码	响应压缩未解压或编码未转换	设置`CURLOPT_ENCODING`，`mb_convert_encoding()`
Cookie带不上	没有设置`CURLOPT_COOKIEFILE`或域名不对	检查Cookie文件路径和域名匹配

5. 实操心得与建议

写到这里，该聊一点个人体会了。cURL这套家族函数把我从“靠file_get_contents拼运气”的阶段解放出来，是PHP里少有的“愈研究愈觉得有深度”的东西。刚开始我也遇到过request body莫名为空、SSL证书校验失败、并发请求查了半天才发现是循环写错这类问题，后来形成一套固定的调试流水线：命令行curl先跑，拿到状态码和响应头；再用PHP封装函数跑，明确区分cURL错误和HTTP状态码；最后才看业务返回体。这套流水线帮我定位了至少80%的问题。

还有一个建议：在团队里，不要每处都裸写cURL，封装一个统一的HTTP客户端层，把超时、重试、日志、错误码统一处理掉，会省掉很多隐性bug。可以在类里维护一个CurlHandle，记录每次请求的curl_getinfo()，出问题时可以直接回溯是哪一步、用了什么UA、带了什么Cookie，比对着服务器日志猜快得多。

最后再分享一个小技巧：如果你在调试一个行为诡异的接口，给cURL加一个CURLINFO_HEADER_OUT选项，然后请求结束后用curl_getinfo($ch, CURLINFO_HEADER_OUT)打开发送的完整请求头。很多“为什么我传了参数对方说没收到”的悬案，一看这里的原始请求头就真相大白了。cURL家族值得你在任何PHP项目里花点时间把它用熟，它不会辜负你。