跳到正文

PHP cURL 与 Guzzle 代理:设置与报错处理

PHP cURL 和 Guzzle 里的代理选项、安全的超时设置,以及判断失败来自代理还是目标站的方法。

同一个代理在 cURL 和 Guzzle 里怎么写

同一个代理在 cURL 和 Guzzle 里怎么写
项目PHP cURLGuzzle
代理地址和协议CURLOPT_PROXY 带协议前缀:http://HOST:2222 或 socks5h://HOST:3333'proxy' => 同一个字符串,会写入 CURLOPT_PROXY
账号和密码CURLOPT_PROXYUSERPWD => 'USERNAME:PASSWORD'写在代理 URL 里,或写在 'curl' => [CURLOPT_PROXYUSERPWD => ...]
连接超时CURLOPT_CONNECTTIMEOUT,默认 300 秒'connect_timeout',默认 0,即无限等待
总超时CURLOPT_TIMEOUT,默认 0,不限时'timeout',默认 0,即无限等待

来源:PHP 手册的 cURL 常量、libcurl 的 CURLOPT_PROXY 页面和 Guzzle 的 Request options,2026 年 11 月 17 日读取。Guzzle 文档没有提到 SOCKS5;使用 cURL 处理器时,字符串会直接交给 libcurl。

PHP cURL:代理、超时和错误码

示例用带协议的地址设置代理,用 CURLOPT_PROXYUSERPWD 传账号密码,并设了两个超时。账号密码单独传,密码里的特殊字符就不需要做百分号编码;我们读到的 libcurl 页面没有说明写在代理字符串里的账号密码会不会被解码。希望由代理解析目标域名时用 socks5h://。

curl_exec() 之后读三样东西:curl_errno()(0 表示 cURL 没有出错)、CURLINFO_HTTP_CODE(目标站的响应码)和 CURLINFO_HTTP_CONNECTCODE(代理对 CONNECT 的响应码)。合起来就能判断失败出在代理还是站点。

带错误分类的 PHP cURL 示例

<?php
// PHP cURL extension. Save as check.php and run: php check.php

function fetchViaProxy(string $url, string $proxy, string $userpwd): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_PROXY          => $proxy,     // 'http://HOST:2222' or 'socks5h://HOST:3333'
        CURLOPT_PROXYUSERPWD   => $userpwd,   // 'USERNAME:PASSWORD'
        CURLOPT_CONNECTTIMEOUT => 10,         // PHP default is 300 seconds
        CURLOPT_TIMEOUT        => 30,         // PHP default is 0 = no limit
    ]);
    $body = curl_exec($ch);

    return [
        'body'        => $body,
        'errno'       => curl_errno($ch),                           // 0 = no cURL error
        'error'       => curl_error($ch),
        'http'        => curl_getinfo($ch, CURLINFO_HTTP_CODE),     // answer of the target site
        'connectCode' => curl_getinfo($ch, CURLINFO_HTTP_CONNECTCODE), // answer of the proxy to CONNECT
        'seconds'     => curl_getinfo($ch, CURLINFO_TOTAL_TIME),
    ];
}

function explain(array $r): string
{
    switch ($r['errno']) {
        case 0:   return $r['http'] >= 400 ? "target answered HTTP {$r['http']}" : 'ok';
        case 5:   return 'proxy host name cannot be resolved: check HOST';
        case 7:   return 'cannot open a connection to the proxy or the target: check HOST, PORT, firewall';
        case 28:  return 'timeout: proxy or target too slow, or wrong port';
        case 35:  return 'TLS handshake failed';
        case 52:
        case 56:  return 'connection closed or nothing received: check the protocol matches the port';
        case 97:  return 'proxy handshake failed (SOCKS): check protocol, username and password';
        default:  return "cURL error {$r['errno']}: {$r['error']}";
    }
}

$r = fetchViaProxy('https://ipinfo.io/json', 'http://HOST:2222', 'USERNAME:PASSWORD');
echo explain($r), PHP_EOL;
if ($r['connectCode'] === 407) {
    echo 'The proxy answered CONNECT with 407: check username, password and the IP term', PHP_EOL;
}
echo $r['body'], PHP_EOL;

把 HOST、USERNAME、PASSWORD 换成「我的资产」里的值,端口要和协议对应。错误说明对应 libcurl 的错误码页面。

cURL 错误号对代理意味着什么

cURL 错误号对代理意味着什么
项目libcurl 的含义先查什么
5无法解析代理主机HOST 是否写对、本机 DNS
7无法连接目标或代理HOST 和 PORT、防火墙、协议与端口是否对应
28达到时间限制端口、目标站过慢,或超时设得太短
35TLS 握手失败目标站证书,或本机上拦截 HTTPS 的软件
52、55、56没有返回数据、发送失败、接收失败CURLOPT_PROXY 里的协议要和端口对应:2222 用 http,3333 用 socks5h
97代理握手失败协议、用户名、密码;PHP 8.2 及以上可用 CURLINFO_PROXY_ERROR 获取详情

来源:libcurl 错误码页面和 PHP 手册常量,2026 年 11 月 17 日读取。「先查什么」一栏是我们对这些说明的理解。

Guzzle:proxy 选项和两个异常类

Guzzle 文档里的 proxy 选项可以是适用所有协议的字符串,也可以是带 http、https 和 no 列表的数组。只有不传自己的 proxy 选项时,Guzzle 才会从环境变量读取 NO_PROXY。文档没有提到 SOCKS5,但源码把这个字符串写入 CURLOPT_PROXY,所以用 cURL 处理器时 socks5h:// 地址会原样交给 libcurl。

错误方面,Guzzle 源码只对 cURL 错误 28、6、7、35、52 生成 ConnectException。其他错误,比如 5(代理主机)、56(接收)、97(代理握手),都以没有响应的 RequestException 抛出。目标站返回的 4xx 或 5xx 也是 RequestException(ClientException 或 ServerException),除非把 http_errors 设为 false。

处理两类异常的 Guzzle 示例

<?php
// composer require guzzlehttp/guzzle
// Load Composer's autoload.php here (require the file Composer created in your project).

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ConnectException;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'proxy'           => 'http://HOST:2222',       // or 'socks5h://HOST:3333' for an IP bought as SOCKS5
    'curl'            => [CURLOPT_PROXYUSERPWD => 'USERNAME:PASSWORD'],
    'connect_timeout' => 10,                        // Guzzle default is 0 = wait indefinitely
    'timeout'         => 30,                        // Guzzle default is 0 = wait indefinitely
]);

try {
    $response = $client->request('GET', 'https://ipinfo.io/json');
    echo $response->getBody(), PHP_EOL;
} catch (ConnectException $e) {
    // Guzzle's cURL handler uses this class for errno 6, 7, 28, 35 and 52
    $errno = $e->getHandlerContext()['errno'] ?? '?';
    echo "Connection problem (errno $errno): ", $e->getMessage(), PHP_EOL;
} catch (RequestException $e) {
    if ($e->hasResponse()) {
        echo 'HTTP ', $e->getResponse()->getStatusCode(), PHP_EOL;     // 4xx or 5xx from the target
    } else {
        // other cURL errors, for example 5 (proxy host), 56 (receive) or 97 (proxy handshake)
        $errno = $e->getHandlerContext()['errno'] ?? '?';
        echo "No response (errno $errno): ", $e->getMessage(), PHP_EOL;
    }
}

把 HOST、USERNAME、PASSWORD 换成「我的资产」里的值。关于 errno 的注释对应 Guzzle 7.9 源码。

快速排查

脚本卡住好几分钟

检查 两个超时都设了吗?PHP 的连接超时默认 300 秒、总超时默认 0,Guzzle 的两个默认值都是无限等待。

处理 设置 CURLOPT_CONNECTTIMEOUT 和 CURLOPT_TIMEOUT,或 connect_timeout 和 timeout。

errno 7,或刚连上就出现 56

检查 协议和端口对应吗?按 HTTP 购买的 IP 用 2222,按 SOCKS5 购买的 IP 用 3333。

处理 重新从「我的资产」复制 HOST、PORT 和协议,再用 curl -x 带同样的值测试。

connectCode 为 407,或 errno 97

检查 用户名、密码和 IP 的到期日。

处理 重新复制并用 curl 测试。407 的含义见代理认证指南。

停止条件 如果 curl 用同样的信息也失败,问题在代理信息,不在 PHP。

HTTP 403 或 429 且 errno 为 0

检查 代理是通的:cURL 没有出错,响应来自目标站。

处理 查看目标站的规则并降低请求频率。这不是代理故障。

用 Proxy302 怎么做

  1. 第 1 步

    在自动化页面里选产品。机房 IP 1 天 US$0.25、30 天 US$3.99,各国同价;动态住宅按 GB 计费。没有免费试用。

  2. 第 2 步

    打开「我的资产」,复制 HOST、PORT、USERNAME 和 PASSWORD。租用的 IP 只有一种协议,购买时选定:HTTP 用 2222 端口,SOCKS5 用 3333 端口。

  3. 第 3 步

    先运行 cURL 示例,再运行 Guzzle 示例。读取 ipinfo.io 的返回:IP 和国家应该是代理的。

    预期结果 带代理 IP 的 JSON,没有错误信息。

常见问题

PHP cURL 怎么设置带账号密码的代理?

把 CURLOPT_PROXY 设成带协议的地址,CURLOPT_PROXYUSERPWD 设成 USERNAME:PASSWORD,PHP 手册就是这么描述的。

Guzzle 支持 SOCKS5 代理吗?

文档没有提到。源码把代理字符串写入 CURLOPT_PROXY,而 libcurl 接受 socks5:// 和 socks5h://,所以用 cURL 处理器时可以直接写。请用 ipinfo.io 请求确认。

怎么区分代理错误和目标站错误?

如果 curl_errno() 不是 0,请求没有完成:5、7、97 指向代理,28 是超时。如果是 0 而 CURLINFO_HTTP_CODE 是 4xx 或 5xx,说明代理是通的,是站点返回了这个状态码。

代理挂了为什么脚本等那么久?

PHP 的连接超时默认 300 秒,总超时默认 0(不限时),Guzzle 的默认值是无限等待。请把两个超时都设上。

能在 PHP 里免费试用 Proxy302 吗?

没有免费试用。最小的购买是 1 GB 动态住宅流量,或一个 IP 一天。

参考资料

8
  1. libcurl:CURLOPT_PROXY

    官方文档 · 确认日期:

    2026 年 11 月 17 日读取:可用的协议前缀 http://、https://、socks4://、socks4a://、socks5:// 和 socks5h://(socks5h 由代理解析域名);没写端口时用 1080;用户名和密码可以写在字符串里,也可以用 CURLOPT_PROXYUSERNAME 和 CURLOPT_PROXYPASSWORD 设置;该选项优先于代理环境变量;设为空字符串会关闭代理。

    页面没有说明字符串里的账号密码是否需要百分号编码。

  2. libcurl:错误码

    官方文档 · 确认日期:

    2026 年 11 月 17 日读取:5 无法解析代理主机、6 无法解析目标主机、7 无法连接目标或代理、28 达到时间限制、35 TLS 握手失败、52 没有返回数据、55 发送失败、56 接收失败、97 代理握手失败(详情见 CURLINFO_PROXY_ERROR)。

  3. PHP 手册:cURL 常量

    官方文档 · 确认日期:

    2026 年 11 月 17 日读取:CURLOPT_PROXY、CURLOPT_PROXYUSERPWD([username]:[password])、CURLOPT_PROXYTYPE(默认 CURLPROXY_HTTP)、CURLOPT_CONNECTTIMEOUT(默认 300 秒,0 表示无限等待)、CURLOPT_TIMEOUT(默认 0,传输期间不限时)、CURLINFO_HTTP_CONNECTCODE(CONNECT 响应码)、CURLINFO_PROXY_ERROR(PHP 8.2.0 和 cURL 7.73.0 起)。

  4. PHP 手册:curl_errno 与 curl_getinfo

    官方文档 · 确认日期:

    2026 年 11 月 17 日读取:curl_errno() 返回最近一次操作的错误号,没有错误返回 0;curl_error() 返回错误信息;curl_getinfo() 返回 http_code、total_time、connect_time、primary_ip 等键。

  5. Guzzle 文档:Request options

    官方文档 · 确认日期:

    2026 年 11 月 17 日读取:proxy 选项可以是适用所有协议的字符串,也可以是带 http、https、no 键的数组;账号密码可写在代理 URL 里;只有不传自己的 proxy 选项时才会自动读取 NO_PROXY;connect_timeout 和 timeout 是浮点数,默认 0,即无限等待;http_errors 默认为 true,会把 4xx 和 5xx 变成异常。

    页面没有提到 SOCKS5。

  6. Guzzle 文档:Exceptions

    官方文档 · 确认日期:

    2026 年 11 月 17 日读取:TransferException 是基类;网络错误时抛 ConnectException;RequestException 是 BadResponseException(4xx 对应 ClientException,5xx 对应 ServerException)和 TooManyRedirectsException 的父类。

  7. Guzzle 源码:cURL 处理器(7.9)

    官方文档 · 确认日期:

    2026 年 11 月 17 日读取:字符串形式的 proxy 选项会原样写入 CURLOPT_PROXY;curl 数组里的选项会覆盖处理器的 cURL 选项;只有 cURL 错误 28、6、7、35、52 会生成 ConnectException,其他 cURL 错误(比如 5、56、97)都变成 RequestException。

  8. Proxy302 产品信息和价格表

    产品观察 · 确认日期:

    站点产品信息文件,11 月 10 日对照控制台、后端和价格表核对:机房 IP 按 IP 租用,1 天 US$0.25、30 天 US$3.99,各国同价;HTTP 端口 2222、SOCKS5 端口 3333;按 IP 租用的每个 IP 一种协议;动态住宅走 proxy.proxy302.com,一个账号两种协议都能用;每单最多 100 个;没有免费试用。

准备好试试了吗?

注册账号、充值一次,就能选动态住宅、静态 ISP 或数据中心 IP,几分钟配进你的浏览器。