Go HTTP 客户端Transport ProxyConnectHeader 缺失时怎么办

如果你给 http.Transport 配了 ProxyConnectHeader，但代理端说没有收到，先不要急着改 Header 名称。这个字段有一个很明确的边界：它只用于 Transport 向代理发起 CONNECT 时附加请求头，并不会自动出现在发往目标站点的普通请求里。

官方资料：https://pkg.go.dev/net/http#Transport

排查这类问题，我通常按“有没有代理、有没有 CONNECT、静态字段有没有被动态回调覆盖、回调有没有返回头”四层来走。只要把这四层分开，所谓“缺失”大多能定位到具体配置路径。

先确认请求有没有走 CONNECT

当目标地址是 HTTPS、代理又是支持 CONNECT 的 HTTP 代理时，Transport 会先向代理请求目标的 ip:port 隧道。此时 ProxyConnectHeader 才有发送位置。它的接收者是代理，不是最终的 HTTPS 服务。

因此下面几种现象不能直接证明字段失效：

• 你在目标服务的业务日志里找不到 Proxy-Authorization。TLS 隧道建立后，这个头本来就不属于目标站点的普通请求。
• 请求地址是 http://，没有建立 HTTPS 隧道，因而不会按 HTTPS CONNECT 路径使用它。
• 代理函数返回了 nil，请求直连目标，Transport 没有可发送 CONNECT 头的代理对象。

这里的第一步不是打印所有请求头，而是确认代理选择结果。固定代理可以用 http.ProxyURL，环境代理则由 http.ProxyFromEnvironment 根据 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 决定。

固定代理时使用 ProxyConnectHeader

代理地址和认证方式固定时，直接设置 ProxyConnectHeader 最简单。下面的例子只演示配置边界，认证值用占位符表示；生产环境不要把真实凭据硬编码进源文件。

package main

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

func main() {
    proxyURL, err := url.Parse("http://proxy.example:8080")
    if err != nil {
        log.Fatal(err)
    }

    transport := &http.Transport{
        // 只有请求经过这个代理时，下面的 CONNECT 头才有发送对象。
        Proxy: http.ProxyURL(proxyURL),
        // 这里只放代理需要的头，值应从安全配置来源读取。
        ProxyConnectHeader: http.Header{
            "Proxy-Authorization": []string{"Basic "},
            "X-Proxy-Route":        []string{"blue"},
        },
    }

    client := &http.Client{Transport: transport}
    req, err := http.NewRequestWithContext(
        context.Background(), http.MethodGet, "https://target.example/data", nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close() // 读取完响应后释放连接资源。
    log.Println(resp.Status)
}

这个配置有三个容易忽略的条件：

1. client.Transport 必须确实是你配置过的这个 Transport，而不是被别处替换成 http.DefaultTransport。
2. Proxy 必须为当前请求返回代理 URL；如果 NO_PROXY 排除了目标，环境代理路径就不会出现。
3. Transport 应该复用。每次请求新建一个 Transport 不仅难以观察，还会破坏连接池的复用策略。

按代理和目标动态生成请求头

如果不同代理、不同目标或不同租户需要不同的 CONNECT 头，应该使用 GetProxyConnectHeader。官方字段说明中最关键的一句是：这个回调非空时，ProxyConnectHeader 会被忽略。

也就是说，下面这种写法不会把两个 Header 合并起来：

transport := &http.Transport{
    // 这个静态 map 在回调存在时会被忽略。
    ProxyConnectHeader: http.Header{
        "X-Proxy-Mode": []string{"static"},
    },
    GetProxyConnectHeader: func(
        ctx context.Context, proxyURL *url.URL, target string,
    ) (http.Header, error) {
        // 回调参数能区分代理 URL 和本次 CONNECT 的目标 host:port。
        if proxyURL == nil || target == "" {
            return nil, errors.New("missing proxy or target")
        }

        headers := make(http.Header)
        // 真实认证信息应由调用方按租户或代理安全地取得。
        headers.Set("X-Proxy-Mode", "dynamic")
        return headers, nil
    },
}

上面的片段需要补充 errors、context、net/http 和 net/url 导入。它重点展示的是字段关系：回调返回的 Header 才是 CONNECT 使用的 Header，静态 map 不会再叠加。

回调有三种结果值得单独记住：

用回调错误和 CONNECT 响应缩小范围

当问题从“没看到头”变成“请求失败”，可以给 Transport 配置 OnProxyConnectResponse 观察代理对 CONNECT 的响应。它会在检查 200 OK 之前被调用，适合记录状态码和代理响应头，但不要把认证值写入日志。

transport := &http.Transport{
    Proxy: http.ProxyURL(proxyURL),
    GetProxyConnectHeader: func(
        ctx context.Context, proxyURL *url.URL, target string,
    ) (http.Header, error) {
        // 这里返回错误时，代理可能根本没有收到 CONNECT。
        headers := make(http.Header)
        headers.Set("X-Proxy-Target", target)
        return headers, nil
    },
    OnProxyConnectResponse: func(
        ctx context.Context, proxyURL *url.URL,
        connectReq *http.Request, connectRes *http.Response,
    ) error {
        // 只记录状态和代理地址，避免泄露 CONNECT 认证头。
        log.Printf("proxy=%s status=%s", proxyURL.Host, connectRes.Status)
        return nil
    },
}

注意 OnProxyConnectResponse 是观察 CONNECT 响应的钩子，不是给 CONNECT 增加请求头的入口。增加请求头仍应放在 ProxyConnectHeader 或 GetProxyConnectHeader 中。

四个常见误区

把普通 Header 当成代理 CONNECT 头

req.Header 描述发往目标服务的 HTTP 请求；ProxyConnectHeader 描述发往代理的 CONNECT 请求。两者处在不同连接阶段，不能用目标服务的抓包结果互相证明。

只设置 Header，没有设置 Proxy

没有代理选择结果，就没有 CONNECT 的接收者。先检查 Transport.Proxy 是否生效，以及环境代理是否被 NO_PROXY 排除。

同时设置静态字段和动态回调，期待自动合并

这会产生最典型的误判。只要 GetProxyConnectHeader 非空，静态 ProxyConnectHeader 就不参与本次选择。需要合并时，在回调中显式构造完整 Header。

把连接复用当成“配置没生效”

Transport 会缓存连接。一个已经建立的隧道被复用时，不会为每个普通请求重新发送 CONNECT。调整 Header 后如果一直复用旧连接，观察结果可能不会立即出现；排查时应明确自己是在看新建隧道，还是看已有连接上的后续请求。

最后用这张表收口

相关问题

ProxyConnectHeader 会发送到最终 HTTPS 服务吗？

不会。它面向代理的 CONNECT 请求；隧道建立后，目标服务看到的是隧道内的普通 HTTPS 请求。

什么时候该用 GetProxyConnectHeader？

当请求头依赖代理 URL、目标 host:port、上下文或租户配置时使用。固定值则用 ProxyConnectHeader 更直观。

回调返回 nil、nil 是错误吗？

不是。它表示本次不额外增加 CONNECT 头；如果代理要求认证，最终结果可能是代理拒绝，而不是 Go 自动补齐认证。

为什么只改 Header 仍然看不到新的 CONNECT？

Transport 会复用已经建立的连接。先确认观察到的是新建隧道，并检查代理选择和连接池行为，再判断 Header 是否真正参与。