# ProxyError：Python 中的“无法连接到代理”及 Node.js

> requests.exceptions.ProxyError“无法连接代理”说明：阅读嵌套异常（拒绝、超时、DNS、407、502），并应用相应修复。

- URL: https://crawlrelay.com/zh/docs/errors/cannot-connect-to-proxy/
- 最后更新: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

客户端库错误（Python，Node.js）：每个工具中的精确错误信息、可能原因排序及有效解决方案。

**快速回答 — 代理中的Cannot connect to proxy (ProxyError)是什么意思？**

**“无法连接到代理”** 是一个包装错误：Python 的 requests 和 urllib3 会将实际原因放入其中。请阅读最内层的原因。‘连接被拒绝’或超时意味着主机、端口或网络问题；‘解析失败’表示 DNS 问题；‘隧道连接失败：407’表示凭据问题。对于 CrawlRelay，每种情况都有一行修复方法。

## Cannot connect to proxy (ProxyError)一览

| 属性 | 值 |
| --- | --- |
| 错误 | Cannot connect to proxy (ProxyError) |
| 类型 | 客户端库错误（Python，Node.js） |
| 发送方 | 您的 HTTP 客户端，在连接代理之前或期间 |
| 定义于 | Library error; read the nested cause for the real reason |
| 要重试吗？ | 取决于嵌套的具体原因 |
| 先检查 | 查看最内层异常：拒绝、超时、名称解析或状态码 |

## Cannot connect to proxy (ProxyError)是什么意思？

urllib3 对涉及代理的每次失败都会引发一个 `ProxyError`，requests 会传递该异常。有用的信息位于嵌套异常中，traceback 会在长行末尾打印它。

Node.js 客户端表现不同：它们直接报告套接字错误，如 `ECONNREFUSED` 或 `ETIMEDOUT`，通常不会说明地址是代理的。

## 在Python、curl、Node.js和浏览器中'Cannot connect to proxy'是什么样？

每个工具中相同的失败会有不同的提示信息。请在日志中搜索以下信息：

- **拒绝连接：** `ProxyError('Unable to connect to proxy', NewConnectionError(... Connection refused))`
- **DNS：** `NameResolutionError(... Failed to resolve ...)` 在 `ProxyError` 内
- **凭据问题：** `OSError('Tunnel connection failed: 407 Proxy Authentication Required')`
- **网关错误：** `OSError('Tunnel connection failed: 502 Bad Gateway')`
- **Node.js：** `Error: connect ECONNREFUSED`、`ETIMEDOUT` 或 `ENOTFOUND`，后跟代理地址

## 导致'Cannot connect to proxy'的原因是什么？

最可能的首要原因：

- 代理 URL 中的**主机或端口错误**。
- **缺少协议头**：某些库对没有 `http://` 的 `host:port` 解析结果令人意外。
- 网络或服务器上**阻止出站流量**。
- CONNECT 步骤中出现的**凭据或网关错误**，被同一异常包装。
- 环境变量如 `HTTPS_PROXY` 指向旧代理，覆盖代码配置。

## 如何一步步诊断'Cannot connect to proxy'？

1. 打印完整异常并查看最后嵌套的原因。
2. 打印 `requests.utils.get_environ_proxies(url)` 或 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 变量，查看还有什么配置。
3. 在同一台机器上运行下面的 curl 测试。
4. 将原因与下面的修复列表匹配。

*用curl测试失败的URL（HTTP端口，详细模式）*

```bash
# Use the URL that fails; with https://api.ipify.org instead, you test the gateway alone.
# "HTTP/1.1 200 Connection established" first, then the site's own status: the site answered.
curl -v -x http://USERNAME:PASSWORD@gw.crawlrelay.com:7777 https://TARGET_URL

# Same test through the SOCKS5 port, with DNS resolved at the exit
curl -v --socks5-hostname gw.crawlrelay.com:7778 --proxy-user USERNAME:PASSWORD https://TARGET_URL
```

## 如何修复'Cannot connect to proxy'？

- **拒绝或超时：** 修正主机和端口，或开放出站流量到网关。
- **解析失败：** 检查机器上的 DNS；尝试用 `nslookup` 访问主机。
- **407：** 修正并 URL 编码凭据。参考 [407 代理认证要求](https://crawlrelay.com/zh/docs/errors/407-proxy-authentication-required/)。
- **502 或 504：** 在新出口重试。参考 [502](https://crawlrelay.com/zh/docs/errors/502-bad-gateway/) 和 [504](https://crawlrelay.com/zh/docs/errors/504-gateway-timeout/)。
- **不需要的环境代理：** 在 requests 中设置 `session.trust_env = False`，或清理环境变量。

*Python：用编码后的凭证构建代理URL*

```python
from urllib.parse import quote

import requests

user = "USERNAME-country-us"
password = "p@ss:word/1"  # example containing special characters

# safe="" also encodes "/", "@" and ":" inside the credentials
proxy = "http://{}:{}@gw.crawlrelay.com:7777".format(
    quote(user, safe=""), quote(password, safe="")
)
proxies = {"http": proxy, "https": proxy}  # http:// for both keys

r = requests.get("https://api.ipify.org", proxies=proxies, timeout=(10, 30))
print(r.status_code, r.text)
```

## 遇到'Cannot connect to proxy'后要重试吗？

只重试可能会变化的网络级原因：如超时和 502、504 等网关错误。拒绝连接、DNS 失败或 407 错误会一直重现，直到你修改配置，因此应将它们视为致命错误。

## Cannot connect to proxy (ProxyError)如何应用于CrawlRelay？

对 CrawlRelay，代理 URL 是 `http://USERNAME:PASSWORD@`，后接下面列出的网关主机和 HTTP 端口，对 HTTP 和 HTTPS 目标均适用。requests 中 `http` 和 `https` 键使用相同的 `http://` URL：协议头指定与代理通信的协议，而不是访问网站的协议。

网关：`gw.crawlrelay.com`，端口7777（通过CONNECT的HTTP、HTTPS）和端口7778（SOCKS5）。用户名格式：`USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}`。相关内容：[SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/zh/docs/errors/ssl-wrong-version-number/) · [407](https://crawlrelay.com/zh/docs/errors/407-proxy-authentication-required/) · [Python 指南](https://crawlrelay.com/zh/docs/python/)。

## Cannot connect to proxy (ProxyError)：开发者常问的问题

### 使用代理时，“超出最大重试次数，URL”为何出现？

这意味着 urllib3 在重试限额内放弃，真正原因在消息的“原因”部分。使用代理时，该部分通常是有嵌套原因的 ProxyError：连接被拒、超时、名称解析失败或隧道状态（如 407）。

### requests 为什么会用我没配置的代理？

requests 默认读取 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 环境变量，Windows 还会读取系统代理设置。遗留值会覆盖你的预期。设置 `session.trust_env = False`，或在每次请求时显式传递代理。

### 代理地址前应写 http:// 还是 https://？

即使网站使用 HTTPS，HTTP 代理 URL 也应写成 `http://`。协议头描述客户端如何与代理通信。写成 `https://` 会让新版 urllib3 启动与代理的 TLS 通信，这会导致传统 HTTP 代理端口出现 SSL 错误失败。

## 本参考中的其他代理错误

- [401 Unauthorized vs 407](https://crawlrelay.com/zh/docs/errors/401-unauthorized/)
- [403 Forbidden](https://crawlrelay.com/zh/docs/errors/403-forbidden/)
- [407 Proxy Authentication Required](https://crawlrelay.com/zh/docs/errors/407-proxy-authentication-required/)
- [429 Too Many Requests](https://crawlrelay.com/zh/docs/errors/429-too-many-requests/)
- [502 Bad Gateway](https://crawlrelay.com/zh/docs/errors/502-bad-gateway/)
- [503 Service Unavailable](https://crawlrelay.com/zh/docs/errors/503-service-unavailable/)
- [504 Gateway Timeout](https://crawlrelay.com/zh/docs/errors/504-gateway-timeout/)
- [Cannot connect to proxy (ProxyError)](https://crawlrelay.com/zh/docs/errors/cannot-connect-to-proxy/)
- [Connection reset by peer (ECONNRESET)](https://crawlrelay.com/zh/docs/errors/connection-reset/)
- [ERR_PROXY_CONNECTION_FAILED](https://crawlrelay.com/zh/docs/errors/err-proxy-connection-failed/)
- [ERR_TUNNEL_CONNECTION_FAILED](https://crawlrelay.com/zh/docs/errors/err-tunnel-connection-failed/)
- [Read timed out (ReadTimeout)](https://crawlrelay.com/zh/docs/errors/read-timeout/)
- [SOCKS5 proxy errors](https://crawlrelay.com/zh/docs/errors/socks5-proxy-errors/)
- [SSL: CERTIFICATE_VERIFY_FAILED](https://crawlrelay.com/zh/docs/errors/ssl-certificate-verify-failed/)
- [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/zh/docs/errors/ssl-wrong-version-number/)

**带有涵盖失败案例文档的住宅代理** 来自US$0.50/GB的CrawlRelay住宅代理，流量永不过期。 [查看价格](https://crawlrelay.com/zh/pricing/) · [快速开始](https://crawlrelay.com/zh/docs/)

---

CrawlRelay: CrawlRelay 是为开发者设计的住宅代理和 4G/5G 移动代理轮换服务，适用于爬虫和 AI 数据管道：按需付费且流量永不过期，最低流量从 US$0.50/GB 起，支持加密货币支付，无需上传身份证明。无需 KYC —— 无需身份证、自拍和任何证件。支持加密货币支付。