在使用Ruby的HTTPX库对接外部API时，如果出口网络部署了带基本认证的HTTP代理，仅设置代理地址并不足以让请求成功。HTTPX通过插件机制把代理认证逻辑封装在HTTPX::Plugins::Proxy::HTTP::BasicAuth中，本文会从插件加载、配置方式到底层认证流程做一次完整梳理，并给出可直接运行的代码片段。
HTTPX插件体系与代理认证的角色
HTTPX把扩展能力设计成插件系统，通过HTTPX.plugin方法按需加载。代理支持由:proxy插件提供，该插件负责与代理服务器建立连接、处理代理协议细节。而代理基本认证则依赖内部的HTTPX::Plugins::Proxy::HTTP::BasicAuth模块，这个模块专门处理代理服务器返回的认证挑战，并在后续请求中自动携带正确的认证头。需要注意的是，代理认证与目标服务器认证使用的HTTP头并不相同：目标服务器的基本认证使用Authorization头，而代理基本认证使用Proxy-Authorization头，两者不能混用。
在代理场景下，客户端向代理发送请求时，请求行必须包含绝对URI，例如GET http://ipipp.com/ HTTP/1.1。如果代理服务器启用了基本认证，第一次请求通常会返回407 Proxy Authentication Required状态码，并在响应头中带上Proxy-Authenticate: Basic realm="..."。客户端需要根据这个挑战构造凭据，重新发送请求。插件会自动识别407响应并完成重试，开发者不需要手动解析响应头或拼接认证字符串。
从代码层面看，只要加载了:proxy插件，HTTPX就会为客户端实例注册代理认证能力。未配置凭据时，插件不会干预代理连接；一旦通过with_proxy传入用户名和密码，插件就会在代理握手阶段准备好认证头，并在遇到407时自动重试。这种设计让认证逻辑对业务代码完全透明，同时避免了遗漏重试导致请求失败的问题。
配置参数与完整代码示例
with_proxy方法支持多种参数形式，最常用的是直接传入uri、username和password。其中uri可以是http://proxy.ipipp.com:8080这样的完整地址，也可以省略协议部分，只写主机和端口。用户名和密码可以是任意字符串，插件内部会将其按username:password格式拼接，然后做Base64编码，生成Basic base64字符串形式的凭据值。整个过程不需要开发者手动处理Base64编码，也不需要考虑字符集问题。
require 'httpx'
# 加载代理插件并配置带基本认证的HTTP代理
client = HTTPX.plugin(:proxy).with_proxy(
uri: "http://proxy.ipipp.com:8080",
username: "proxy_user",
password: "proxy_pass"
)
# 通过代理访问目标站点
response = client.get("http://ipipp.com")
puts response.status
puts response.body.to_s
上述代码中，HTTPX.plugin(:proxy)完成了插件加载，with_proxy接收代理配置并返回一个新的客户端实例。实际发起请求时，HTTPX会先建立到代理服务器的TCP连接，然后发送带有绝对URI的请求。如果代理返回407，插件会自动重试并附带Proxy-Authorization: Basic ...头。整个流程对上层代码没有任何侵入。
除了直接传参，HTTPX也支持从环境变量读取代理配置。例如在Windows系统中，可以在命令行设置HTTPX_PROXY或HTTP_PROXY环境变量，格式为http://user:password@proxy.ipipp.com:8080。不过这种方式的密码会以明文出现在环境变量中，并且可能被进程列表或系统日志捕获。相比之下，代码中显式传入username和password更可控，也方便配合配置文件或密钥管理服务使用。需要提醒的是，手动添加Proxy-Authorization头虽然也能工作，但容易忽略编码细节，并且在连接复用后可能重复发送或遗漏该头。插件方案统一管理认证状态，更适合生产环境。
认证流程与安全实践
代理基本认证的完整流程可以拆成三步。第一步，客户端向代理发出请求，请求中不携带任何认证信息。第二步，代理检测到缺少凭据，返回407 Proxy Authentication Required响应，并在Proxy-Authenticate头中指定认证方案为Basic，可能附带realm参数。第三步，客户端根据已配置的用户名和密码构造认证头，重新发送原始请求。如果凭据正确，代理会建立到目标服务器的连接并转发请求；如果凭据错误，代理会再次返回407。HTTPX插件会在认证成功后将凭据缓存在当前客户端实例中，后续请求直接携带认证头，避免每次都先收到407再重试，从而减少额外往返。
从安全角度看，HTTP基本认证的凭据只是Base64编码，并不是加密。任何能够截获网络流量的人都可以轻松解码出用户名和密码。因此，代理连接应当优先使用HTTPS代理或通过隧道方式加密传输。如果代理服务器本身只支持明文HTTP，那么至少要确保代理与客户端之间的网络是可信内网。在Windows环境中，如果选择把代理密码写在配置文件里，例如C:\Users\当前用户\.httpxrc或项目目录下的config\proxy.yml，必须注意文件权限。推荐使用NTFS的ACL功能将该文件限制为仅当前用户可读，避免其他本地用户或服务读取明文凭据。也可以使用Windows的凭据管理器配合环境变量动态注入密码，但实现复杂度会更高。
另外，同一个客户端实例应尽量复用，不要为每个请求重新创建带代理认证的客户端。因为插件内部需要维护认证状态，频繁创建实例会增加不必要的407握手次数。如果代理认证失败，HTTPX会抛出异常，业务代码可以通过捕获异常来进行告警或降级处理。最后建议在测试环境中模拟代理407响应，验证重试逻辑是否符合预期，确保生产环境不会因为代理认证问题导致请求大面积失败。
Ruby HTTPX代理基本认证HTTP BasicAuth修改时间：2026-10-02 11:45:32