# net::ERR_TUNNEL_CONNECTION_FAILED出现的原因及解决方法

> Chrome、Playwright或Puppeteer中使用代理时出现net::ERR_TUNNEL_CONNECTION_FAILED，说明CONNECT隧道失败。找到底层状态码并修复。

- URL: https://crawlrelay.com/zh/docs/errors/err-tunnel-connection-failed/
- 最后更新: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

Chromium网络错误：每个工具中的精确错误信息、可能原因排序及有效解决方案。

**快速回答 — 代理中的ERR_TUNNEL_CONNECTION_FAILED是什么意思？**

**net::ERR_TUNNEL_CONNECTION_FAILED**表示Chrome请求代理开启到HTTPS站点的隧道，代理未响应`200 Connection established`。浏览器隐藏了真实状态码。在 CrawlRelay住宅代理中，通常因Playwright或Puppeteer缺少凭证，或目标无法访问网关。用`curl -v`重现查看真实状态码。

## ERR_TUNNEL_CONNECTION_FAILED一览

| 属性 | 值 |
| --- | --- |
| 错误 | ERR_TUNNEL_CONNECTION_FAILED |
| 类型 | Chromium网络错误 |
| 发送方 | 在代理拒绝或连接失败后浏览器报错 |
| 定义于 | CONNECT method: RFC 9110, section 9.3.6 |
| 要重试吗？ | 先确认背后的状态码 |
| 先检查 | 用curl -v重现以查看CONNECT的真实状态 |

## ERR_TUNNEL_CONNECTION_FAILED是什么意思？

要通过HTTP代理加载HTTPS页面，浏览器先发送`CONNECT host:443`请求。代理若回应200，浏览器在隧道内启动TLS连接；其它状态，如407、403或502，会终止尝试，Chromium报一个通用错误。 

因此这个错误提示的是失败位置（隧道）但不指明原因。原因即代理返回的状态码，curl能帮你看见。

## 在Python、curl、Node.js和浏览器中ERR_TUNNEL_CONNECTION_FAILED是什么样？

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

- **Playwright:** `page.goto: net::ERR_TUNNEL_CONNECTION_FAILED at https://...`
- **Puppeteer:** `Error: net::ERR_TUNNEL_CONNECTION_FAILED at https://...`
- **Chrome 地址栏:** 显示“无法访问此网站”及代码 `ERR_TUNNEL_CONNECTION_FAILED`
- **使用 Selenium 和 Chrome:** 出现同样代码，包含在 `WebDriverException` 中

## 导致ERR_TUNNEL_CONNECTION_FAILED的原因是什么？

最可能的首要原因：

- **未发送凭据**（隐藏的 407）。Chrome 会忽略 `--proxy-server` 中的用户名和密码。
- **目标拒绝访问**（隐藏的 403），如代理使用政策所阻止的类别。
- **目标无法到达**（隐藏的 502 或 504）：死主机、拼写错误或出口的 DNS 失败。
- **端口错误**：将浏览器指向 SOCKS5 端口当作 HTTP，或反之。

## 如何一步步诊断ERR_TUNNEL_CONNECTION_FAILED？

1. 使用带有 `-v` 的 curl 运行相同 URL（命令如下）并读取 `CONNECT` 后的行。
2. `407` 表示需要凭据；`403` 表示目标被拒绝；`502` 或 `504` 表示目标或出口问题。
3. 确认浏览器为 `http://` 代理服务器使用 HTTP 端口。
4. 在访问真实目标前，先测试简单页面如 `https://api.ipify.org`。

*用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
```

## 如何修复ERR_TUNNEL_CONNECTION_FAILED？

- **Playwright:** 在 `proxy` 选项中传递 `server`、`username` 和 `password`，可针对浏览器或上下文。详见 [Playwright 指南](https://crawlrelay.com/zh/docs/playwright/)。
- **Puppeteer:** 使用 `--proxy-server=http://host:port` 启动，并在首次 `goto` 前调用 `page.authenticate()`。详见 [Puppeteer 指南](https://crawlrelay.com/zh/docs/puppeteer/)。
- **Selenium:** 运行一个本地小转发器，添加凭据。详见 [Selenium 指南](https://crawlrelay.com/zh/docs/selenium/)。
- **检查目标** 是否符合我们的 [可接受使用政策](https://crawlrelay.com/zh/acceptable-use/)。

*Playwright（Python）：凭证作为独立字段*

```python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        "server": "http://gw.crawlrelay.com:7777",
        "username": "USERNAME-country-us",
        "password": "PASSWORD",
    })
    page = browser.new_page()
    response = page.goto("https://api.ipify.org")
    print(response.status, page.inner_text("body"))
    browser.close()
```

## 遇到ERR_TUNNEL_CONNECTION_FAILED后要重试吗？

仅当已知隐藏状态时才重试。隐藏的 407 或 403 会一直重复；需修正配置。隐藏的 502 或 504 可在新出口重试，类似任何网关错误。

## ERR_TUNNEL_CONNECTION_FAILED如何应用于CrawlRelay？

CrawlRelay 的 HTTP 端口通过 `CONNECT` 隧道传递 HTTPS，所有基于 Chromium 的工具均支持。浏览器请使用 HTTP 端口：Chromium 不支持带用户名和密码的 SOCKS5。

网关：`gw.crawlrelay.com`，端口7777（通过CONNECT的HTTP、HTTPS）和端口7778（SOCKS5）。用户名格式：`USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}`。相关内容：[407 代理认证要求](https://crawlrelay.com/zh/docs/errors/407-proxy-authentication-required/) · [ERR_PROXY_CONNECTION_FAILED](https://crawlrelay.com/zh/docs/errors/err-proxy-connection-failed/) · [Playwright 指南](https://crawlrelay.com/zh/docs/playwright/)。

## ERR_TUNNEL_CONNECTION_FAILED：开发者常问的问题

### 为什么 curl 能用而 Playwright 显示 ERR_TUNNEL_CONNECTION_FAILED？

因为 curl 会从代理 URL 传递凭据，而 Chromium 会忽略写在代理服务器地址中的凭据。在 Playwright 中，需将 `username` 和 `password` 作为 `proxy` 选项的独立字段传递。在 Puppeteer 中，在导航前调用 `page.authenticate()`。

### 我能在 Chrome 中使用带身份验证的 SOCKS5 代理吗？

不直接支持。Chromium 支持 SOCKS5 代理，但不支持 SOCKS5 用户名密码认证。改用网关的 HTTP 端口，该端口通过 CONNECT 隧道处理 HTTPS，或运行本地转发器为浏览器认证。

### ERR_TUNNEL_CONNECTION_FAILED 是不是网站引起的？

很少直接。隧道位于浏览器和代理之间，所以错误发生在网站看到 TLS 握手之前。网站可能是间接原因，当它无法访问时，代理会对 CONNECT 请求返回 502 或 504。

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

- [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 —— 无需身份证、自拍和任何证件。支持加密货币支付。