当客户端通过 HTTP 代理访问 HTTPS 网站时，代理服务器无法直接读取加密流量，因此必须先建立一条透明的 TCP 隧道。这个隧道由 CONNECT 方法发起，代理收到 CONNECT 请求后会尝试连接目标服务器，成功后返回 200 Connection Established，之后客户端与目标服务器之间的所有 TLS 握手和应用数据都通过该隧道转发。Ruby HTTPX 的 HTTPX::Plugins::Proxy::HTTP::Connect 插件正是这一流程的封装，理解它有助于排查代理环境下的各种网络问题。
CONNECT 方法的工作流程与报文细节
CONNECT 是 HTTP 协议中专门用于建立隧道的方法。与 GET、POST 这类直接获取资源的方法不同，CONNECT 请求的目标不是一个路径，而是主机名和端口号。客户端向代理发送的请求行格式为 CONNECT ippipp.com:443 HTTP/1.1，同时必须携带 Host 头，表明要连接的目标地址。代理收到后，会尝试与 ippipp.com 的 443 端口建立 TCP 连接。
如果连接成功，代理返回 HTTP/1.1 200 Connection Established，此时代理不再解析后续数据，而是进入双向透传模式。客户端随后可以在该隧道上直接与目标服务器进行 TLS 握手，握手完成后发送加密的 HTTP 请求。整个过程代理看到的是加密后的字节流，无法解密内容，这也正是 HTTPS 代理保持安全性的关键。
CONNECT ippipp.com:443 HTTP/1.1 Host: ippipp.com:443 Proxy-Authorization: Basic dXNlcjpwYXNz HTTP/1.1 200 Connection Established
如果目标主机不可达或端口被拒绝，代理通常会返回 502 Bad Gateway 或 504 Gateway Timeout，客户端需要根据响应状态码判断隧道是否建立成功。Ruby HTTPX 内部的 Connect 插件会解析这些响应，并在隧道建立失败时抛出对应的异常或返回错误结果。
在 Ruby HTTPX 中加载 Connect 插件
HTTPX 采用插件机制扩展功能，代理功能由 :proxy 插件提供，而 CONNECT 隧道逻辑则封装在 HTTPX::Plugins::Proxy::HTTP::Connect 类中。实际使用时，开发者通常只需要加载 :proxy 插件并指定代理服务器地址。当请求目标是 HTTPS 时，HTTPX 会自动识别并使用 CONNECT 方法建立隧道，无需手动干预。
下面是一个基本示例，通过本地 HTTP 代理访问 HTTPS 站点：
require "httpx"
require "httpx/plugins/proxy"
client = HTTPX.plugin(:proxy, server: "http://127.0.0.1:8080")
response = client.get("https://ippipp.com")
puts response.status
puts response.body.to_s在这个例子中，server 参数指向代理地址，HTTPX 会先与 127.0.0.1:8080 建立连接，然后发送 CONNECT 请求到 ippipp.com:443。如果代理返回 200，HTTPX 会继续完成 TLS 握手并发送 GET 请求。整个过程对调用方完全透明，开发者可以像直接请求一样处理响应。
如果需要深入了解插件加载顺序，可以查看 HTTPX 的源码目录。Connect 插件通常作为 Proxy 插件的内部依赖自动注册，它实现了隧道建立、状态码校验以及连接升级等逻辑。对于自定义代理场景，也可以基于该类扩展更复杂的认证或连接复用策略。
代理认证与自定义头部处理
很多企业代理要求客户端提供认证信息，否则会返回 407 Proxy Authentication Required。HTTPX 允许直接在代理地址中嵌入用户名和密码，插件会将其转换为 Proxy-Authorization 头并附加到 CONNECT 请求中。这样认证只发生在客户端与代理之间，目标服务器不会看到代理凭证。
require "httpx"
require "httpx/plugins/proxy"
proxy_url = "http://user:pass@127.0.0.1:8080"
client = HTTPX.plugin(:proxy, server: proxy_url)
response = client.get("https://ippipp.com")
puts response.status如果代理使用其他认证方式，比如 NTLM 或 Digest，则需要加载相应的认证插件，并确保它被代理插件正确调用。此外，有些代理会对 CONNECT 请求中的 User-Agent 或其他头字段做限制，这时可以通过请求级别的 headers 参数添加自定义值。不过需要注意，这些自定义头是否会被附加到 CONNECT 请求上，取决于 HTTPX 插件内部的实现。
对于需要动态切换代理的场景，HTTPX 支持会话级配置，开发者可以创建多个 client 实例，分别绑定不同的代理服务器。这样可以避免频繁修改全局配置，也能更好地隔离不同业务线的代理策略。
常见错误与调试技巧
使用 CONNECT 隧道时最常见的错误是 407 Proxy Authentication Required，这通常意味着代理地址中缺少凭证或凭证错误。排查时可以先使用 curl 命令验证代理连通性：
curl -x http://127.0.0.1:8080 https://ippipp.com -v
502 Bad Gateway 和 504 Gateway Timeout 则指向代理无法连接目标主机，可能是目标域名解析失败、防火墙拦截或代理出口 IP 被目标站点封禁。此时需要检查代理服务器的网络策略，并确认目标端口是否允许出站流量。
另一个容易忽略的问题是 TLS 握手失败。由于 CONNECT 建立的是 TCP 隧道，TLS 握手发生在客户端与目标服务器之间，代理只负责转发字节流。如果客户端证书、根证书或加密套件不匹配，即使隧道建立成功，后续握手也会失败。HTTPX 会抛出类似 SSL_connect returned=1 errno=0 state=error 的异常，这通常与代理无关，而是客户端 TLS 配置问题。
开启 HTTPX 的日志功能可以更直观地看到 CONNECT 请求和响应。通过加载 :logging 插件并设置日志级别，开发者能够观察代理交互的完整过程，从而快速定位问题节点。
总结
Ruby HTTPX 的 HTTPX::Plugins::Proxy::HTTP::Connect 插件让 HTTPS 代理访问变得简单可靠。它自动完成 CONNECT 报文构造、状态码校验和隧道建立，开发者只需关注代理地址与认证配置。理解 CONNECT 方法的工作原理，有助于在出现 407、502 或 TLS 握手错误时快速判断问题所在。
总体来看，HTTPX 的代理插件设计清晰，将 CONNECT 隧道与普通 HTTP 转发分离，并允许通过插件组合扩展认证和日志能力。只要理解代理隧道建立的两个阶段，即先 CONNECT 后 TLS，就能避免大部分配置错误，并在实际项目中稳定使用 HTTPS 代理。
Ruby HTTPXHTTP代理CONNECT隧道修改时间：2026-08-23 07:57:59