Go http.CookieJar 出错时怎么排查域匹配

Go 的 http.Client 明明收到了登录 Cookie，换到子域名请求却变成未登录，通常不是 Jar 随机丢数据，而是 Cookie 的域匹配条件没有成立。排查时先固定两件事：Cookie 是从哪个主机收到的，以及目标请求最终访问哪个主机。

官方文档入口：https://pkg.go.dev/net/http/cookiejar。cookiejar.Jar 会把 Cookie 的 Domain、接收主机和目标 URL 放在同一套规则下判断；端口不参与 Cookie 的域匹配，但协议会影响 Secure Cookie。

先确认 Cookie 的域归属类型

调用 jar.SetCookies(receiveURL, cookies) 时，第二个参数只是 Cookie 描述，真正的域归属还要结合第一个参数的主机。没有 Domain 属性的 Cookie 会被记录为 host-only，目标主机必须等于接收主机；显式写了 Domain 的 Cookie 才可能匹配子域。

例如登录地址是 https://auth.example.com/login：不写 Domain 的 sid 只服务于 auth.example.com；写成 Domain=example.com 后，api.example.com 才有机会拿到它。这里的“有机会”很重要，Path、Secure 和过期时间仍会继续筛选。

用四组主机对照定位不匹配

把同一个 Cookie 放入 Jar 后，不要只测试一个目标地址。最小对照表能很快说明问题：

源码里的核心判断可以概括为：主机完全相等时通过；否则必须不是 host-only，并且目标主机以 . 加 Cookie 域结尾。也就是说，badexample.com 不能因为字符串包含 example.com 就算匹配。

package main

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

func main() {
    // 用同一接收主机写入两类 Cookie，专门观察 Domain 的影响。
    jar, err := cookiejar.New(nil)
    if err != nil {
        panic(err) // Jar 创建失败时不要继续做空结果判断。
    }
    receive, err := url.Parse("https://auth.example.com/login")
    if err != nil {
        panic(err) // 固定示例 URL 也要保留解析错误处理。
    }
    jar.SetCookies(receive, []*http.Cookie{
        {Name: "host_sid", Value: "only-host"},
        {Name: "domain_sid", Value: "all-subdomains", Domain: "example.com"},
    })

    targets := []string{
        "https://auth.example.com/me", // 原主机：两类 Cookie 都可能匹配。
        "https://api.example.com/me",  // 子域：只有 domain_sid 可能匹配。
        "https://example.net/me",      // 无关域：两类都不应匹配。
    }
    for _, raw := range targets {
        target, err := url.Parse(raw)
        if err != nil {
            panic(err) // 目标地址无效时先修复输入，而不是分析 Cookie。
        }
        fmt.Printf("%s -> ", target.Host)
        for _, cookie := range jar.Cookies(target) {
            fmt.Printf("%s=%s; ", cookie.Name, cookie.Value) // 只打印当前主机可发送的 Cookie。
        }
        fmt.Println()
    }
}

这段代码的输出应按表格呈现：原主机看到两个名字，子域只看到 domain_sid，无关域为空。若实际结果完全不同，优先检查传给 SetCookies 和 Cookies 的 URL，以及 Client.Jar 是否是这个实例。

排除规范化、公共后缀和 IP 边界

域名看起来相近，不代表传给 cookiejar 的规范化主机相同。标准库会去掉主机端口和完整域名的尾随点，并按 ASCII 形式转小写；因此调试日志最好同时打印 u.Host、u.Hostname() 和 cookie.Domain，不要只看业务配置中的原始字符串。

公共后缀是另一道边界。配置 golang.org/x/net/publicsuffix 的 publicsuffix.List 后，Jar 能用公开后缀数据判断哪些域不能被跨站设置。cookiejar.New(nil) 对简单单域测试很方便，但官方文档明确提醒：没有 Public Suffix List 不适合当作生产安全配置。

IP 地址也不要套用子域逻辑。标准库对 Cookie 的 IP Domain 要求与接收主机相等，并按 host-only 方式处理；127.0.0.1 与另一个 IP 不会因为“看起来属于同一网段”而匹配。若开发环境在 localhost、IP 和真实域名之间切换，应该分别建立测试用例。

把域匹配检查接入请求调试

如果使用 http.Client{Jar: jar}，客户端会在发送请求前查询 Jar，并在收到响应后用请求 URL 更新 Jar。手工调用 jar.Cookies(targetURL) 时，必须传入真正要请求的目标 URL；把登录 URL 当作读取 URL，会掩盖跨子域失败。

// req 是准备发送的请求；这里仅做发送前的域匹配观察。
targetURL := req.URL
for _, cookie := range jar.Cookies(targetURL) {
    fmt.Printf("host=%s cookie=%s\n", targetURL.Hostname(), cookie.Name) // 记录目标主机与可发送名称。
}

// Client.Jar 与上面的 jar 必须指向同一实例，否则观察结果没有参考价值。
client := &http.Client{Jar: jar}
resp, err := client.Do(req)
if err != nil {
    return err // 网络错误与 Cookie 域匹配是两条独立线索，先分开记录。
}
defer resp.Body.Close() // 读取响应后及时释放连接资源。

修复时不要先把所有 Cookie 都改成 Domain=.example.com。先确认业务是否真的需要跨子域共享；如果只需要回到登录主机，保留 host-only 更窄。若必须跨子域，再让服务端在正确的父域上设置 Domain，并用原主机、目标子域、兄弟域三组地址复查。

常见问题

为什么响应里有 Set-Cookie，换到子域后 jar.Cookies 却为空？

最常见原因是响应没有设置 Domain，Cookie 因而是 host-only，只能回到产生它的原主机。确认响应请求 URL 的主机，再决定是否需要服务端显式设置父域。

Cookie 的 Domain 写成带点和不带点有区别吗？

标准库会去掉 Domain 属性开头的一个点再处理，前导点不是扩大范围的开关；真正决定范围的是接收主机、规范化后的域名和 host-only 状态。

给 cookiejar.New(nil) 配公共后缀列表就能解决所有跨域问题吗？

不能。Public Suffix List 只解决公共后缀边界，不能让无关域匹配，也不能把 host-only Cookie 变成 domain Cookie；跨域范围仍需由服务端的 Domain 属性决定。

排查 http.CookieJar 域匹配时，按“接收 URL → Cookie.Domain → HostOnly → 目标 URL → 公共后缀/IP”记录证据，通常一次对照就能区分 Jar 没保存、域名不匹配和其他属性筛选。