在 laravel 10 中，原生 curl 不受框架异常处理机制接管，需手动检查 curl_exec() 返回值及 curl_errno()/curl_error() 并主动抛出异常；推荐封装为 curlexception，在 handler 中统一响应，同时注意日志脱敏与禁用 curlopt_verbose。
在 Laravel 10 中，直接使用原生 cURL（比如 curl_init()）不属于框架 HTTP 客户端体系，它绕过了 Laravel 的异常处理机制，因此异常不会自动进入 App\Exceptions\Handler，也不会被日志、JSON 响应等统一策略接管。捕获它的异常，关键在于**手动检查执行结果并主动抛出或处理**。
原生 cURL 必须检查返回值和错误码
Laravel 不会自动包装或拦截原生 cURL 调用，curl_exec() 失败时默认返回 false，但不会抛出 PHP 异常。你必须显式判断：
- 调用
curl_exec($ch)后，先检查是否为false - 再调用
curl_errno($ch)和curl_error($ch)获取具体错误信息 - 根据错误类型决定是记录日志、抛出自定义异常，还是返回友好响应
推荐封装成可捕获的异常流程
避免在业务逻辑里散落大量 if (false === $res)，建议封装一个工具方法，统一处理并抛出语义化异常：
Leaf Curling & Margin Scorch Diagnosis | 植物卷叶/焦边识别（干旱/病害）
下载
利用农业相机拍摄植物叶片高分辨率图像，通过AI视觉技术检测叶片卷曲方向（向上卷曲或向下卷曲）
- 创建
app/Exceptions/CurlException.php，继承Exception - 在封装函数中：若
curl_exec()返回false，获取curl_error()和curl_errno()，构造带上下文的异常消息 - 在
Handler@render()中识别该异常，按需返回 JSON 或视图（例如 API 请求返回503 Service Unavailable）
注意与 Laravel HTTP 客户端的区别
不要混淆原生 cURL 和 Http::。Laravel 的 HTTP 客户端对连接失败（如超时、DNS 错误）会抛 ConnectionException，而 4xx/5xx 状态码默认不抛异常，只返回 Response 对象供你调用 $response->failed() 判断。原生 cURL 没有这种分层设计，所有错误都靠手动检查。
调试阶段加日志，生产环境过滤敏感信息
如果 cURL 请求含敏感参数（如 token、密码），在记录错误日志前务必清理：
- 用
str_replace()或正则从curl_error()消息中移除 token、密钥等字段 - 避免把完整请求 URL 或 POST body 直接写入日志（尤其是开启 query log 或 debug 模式时）
- 线上环境禁用
curl_setopt($ch, CURLOPT_VERBOSE, true)—— 它会泄露完整通信细节
