Go http.Transport.ProxyConnectHeader 怎样给 HTTPS 代理握手添加请求头

如果 Go 客户端直连 HTTPS 正常，经过企业 HTTP 代理却返回 407，常见原因不是目标请求缺少 Header，而是代理在建立 CONNECT 隧道时没有收到它需要的字段。http.Transport.ProxyConnectHeader 专门解决这一段：它写入发给代理的 CONNECT 请求；目标站点收到的 HTTPS 请求头仍要通过普通的 http.Request.Header 设置。固定字段用静态 Header，必须按代理或目标地址变化时用 GetProxyConnectHeader。

适用范围：本文只讨论 HTTPS 经 HTTP/HTTPS 代理建立 CONNECT 隧道时的请求头，不展开 SOCKS5、自定义 RoundTripper 或代理认证协议本身。

先分清目标请求与代理 CONNECT 请求

HTTPS 经过 HTTP 代理时，Transport 先向代理发送 CONNECT，请求中包含目标的 ip:port；代理同意后，客户端才在隧道内进行 TLS 握手，随后才是目标服务看到的 HTTPS 请求。把业务 Header 放进 ProxyConnectHeader，不会自动转发给目标站点；反过来，给目标请求设置 Header，也不会改变 CONNECT 握手。

因此排查 407 时先问一句：缺字段的是代理，还是目标服务？如果是代理侧认证、路由或追踪字段，才使用下面的配置。

固定字段直接配置 ProxyConnectHeader

所有 CONNECT 请求都需要同一组非敏感路由标记时，可以在 Transport 上配置 Header。代理 URL 只描述代理地址，Header 则描述 CONNECT 握手要带给代理的额外字段。

package main

import (
    "net/http"
    "net/url"
)

func newClient() *http.Client {
    proxyURL, _ := url.Parse("http://proxy.example:8080")

    transport := &http.Transport{
        // Proxy 决定连接走哪个 HTTP 代理。
        Proxy: http.ProxyURL(proxyURL),
        // 这些字段只附加到代理的 CONNECT 请求，不是目标 HTTPS 请求。
        ProxyConnectHeader: http.Header{
            "X-Proxy-Route": {"payments"},
            "X-Request-Trace": {"trace-20261107"},
        },
    }
    return &http.Client{Transport: transport}
}

示例中的路由和追踪字段属于代理域。真正使用时不要把密码、长期 Token 或用户隐私直接写进源码；如果代理认证由代理 URL 的 userinfo 或专门凭据系统管理，应沿用现有认证方案，并在代理日志中确认字段是否被接收。

需要按代理和目标变化时改用动态回调

同一个客户端可能连接多个代理，或者不同目标需要不同的路由字段，这时用 GetProxyConnectHeader 更清楚。回调能拿到上下文、代理 URL 和目标 ip:port；返回错误会让本次 RoundTrip 失败，返回 nil, nil 则表示本次不附加字段。

import (
    "context"
    "errors"
    "net/http"
    "net/url"
)

func newDynamicClient(proxyURL *url.URL) *http.Client {
    transport := &http.Transport{
        // 仍然由 Proxy 选择 HTTP 代理。
        Proxy: http.ProxyURL(proxyURL),
        // 动态回调非空时，ProxyConnectHeader 会被忽略。
        GetProxyConnectHeader: func(ctx context.Context, proxyURL *url.URL, target string) (http.Header, error) {
            if target == "" {
                // 目标为空时拒绝生成含糊的 CONNECT 请求头。
                return nil, errors.New("empty CONNECT target")
            }
            header := make(http.Header)
            // 根据代理主机选择代理侧路由，不把该字段发给目标站点。
            header.Set("X-Proxy-Target", target)
            if proxyURL != nil && proxyURL.Hostname() == "proxy-a.example" {
                header.Set("X-Proxy-Pool", "a")
            }
            return header, nil
        },
    }
    return &http.Client{Transport: transport}
}

动态回调与静态字段不要同时当成两个来源来理解：只要回调非空，Transport 就忽略 ProxyConnectHeader。回调里应返回全新的 Header，避免并发请求共享可变 Map；如果不需要增加字段，明确返回 nil, nil。

把认证和复查边界留在代理侧

当前 Transport 文档还区分了代理 URL、目标地址和代理认证：代理 URL 的 userinfo 可能生成 Proxy-Authorization，标准库会在需要时复制 Header 后补上认证字段。不要把目标服务的 Authorization 当成代理认证，也不要为了“复用 Header”把敏感值放进所有 CONNECT 请求。

复查时按这张清单定位：

• 代理类型确实是 HTTP/HTTPS，且 HTTPS 目标需要 CONNECT 隧道。
• 需要给代理的字段写在 ProxyConnectHeader 或动态回调中，给目标的字段写在普通请求 Header 中。
• 如果配置了 GetProxyConnectHeader，检查是否误以为静态 Header 仍会合并。
• 回调错误、空目标和代理返回 407 分开记录，不要只看最终的 TLS 错误。

一句话记忆：ProxyConnectHeader 管的是“客户端向代理申请通道时说什么”，不是“客户端向目标服务业务请求时说什么”。

相关问题

ProxyConnectHeader 能设置目标接口的 Authorization 吗？不能把它当作目标请求 Header；它属于代理 CONNECT 请求，目标业务 Header 应设置到实际的 http.Request。

静态 Header 和动态回调会合并吗？不会。动态回调非空时，静态 ProxyConnectHeader 会被忽略。

为什么回调返回错误后请求直接失败？这是 Transport 的约定，回调错误会作为本次 RoundTrip 的失败原因返回，适合阻止缺少必要代理字段的请求继续建立隧道。