Go http.CookieJar 如何清理过期 Cookie

我第一次遇到 CookieJar 清理问题，是在一个登录态排查里：服务端明明返回了过期 Cookie，下一次请求却没有带上旧值；但换到另一个路径，状态又像没有清理一样。后来我才意识到，CookieJar 不是一个带“清空按钮”的浏览器面板，它更像一个按 URL 规则筛选 Cookie 的内存容器。

官方文档：https://pkg.go.dev/net/http/cookiejar

先给结论：读取 jar.Cookies(u) 时，已经过期的 Cookie 不会作为目标 URL 的可发送 Cookie 返回；需要主动注销某个 Cookie 时，要通过 SetCookies 传入匹配作用域的删除标记。只有当你想把整个内存会话彻底隔离时，重建一个 Jar 才是更干净的做法。

下面这篇按我实际排查时的顺序展开。图中是原创操作界面和结果示意，不是真实截图；重点是告诉你应该看哪些输入和结果。

先描述 CookieJar 的清理边界

net/http/cookiejar 实现了 http.CookieJar，保存的是内存中的 Cookie。它同时考虑 Cookie 的过期时间、目标 URL、域名和路径，因此“清理”并不等于把容器里所有字符串一次性删掉。

我排查时先把三类情况分开：

• 自然过期：Expires 已经早于当前时间，或者 Cookie 的有效期条件不再满足，读取目标 URL 时不会返回它。
• 主动删除：使用同名 Cookie，并设置 MaxAge ，同时保证 Domain 和 Path 作用域能匹配。
• 整段会话隔离：不再复用旧 Jar，重新创建一个新的 cookiejar.Jar。

这里还有一个容易误解的点：MaxAge == 0 不是“立即删除”，它表示没有通过 Max-Age 指定删除语义。要主动删除，使用负数更直观；要表达自然过期，则使用过去的 Expires。

用过期属性构造可观察样例

为了让问题可以观察，我会先把正常 Cookie 和已经过期的 Cookie 一起放进 Jar，再读取同一个目标 URL。这个例子使用 cookiejar.New(nil) 便于阅读；生产环境建议按照官方文档配置公共后缀列表，避免跨注册域设置 Cookie 的风险。

package main

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

func main() {
    // 这里用 nil 选项演示清理逻辑；生产项目应按部署策略配置 PublicSuffixList。
    jar, err := cookiejar.New(nil)
    if err != nil {
        panic(err)
    }

    target, err := url.Parse("https://api.example.com/account")
    if err != nil {
        panic(err)
    }
    now := time.Now()

    // 正常 Cookie 仍在有效期内，过期 Cookie 的 Expires 已经在当前时间之前。
    jar.SetCookies(target, []*http.Cookie{
        {Name: "sid", Value: "live", Path: "/", Expires: now.Add(time.Hour)},
        {Name: "stale", Value: "old", Path: "/", Expires: now.Add(-time.Minute)},
    })

    fmt.Println("After SetCookies:")
    for _, cookie := range jar.Cookies(target) {
        fmt.Printf("%s=%s\\n", cookie.Name, cookie.Value)
    }

    // MaxAge 小于零表示立即删除同名、同作用域的 Cookie。
    jar.SetCookies(target, []*http.Cookie{
        {Name: "sid", Path: "/", MaxAge: -1},
    })

    fmt.Println("After delete:")
    fmt.Println(len(jar.Cookies(target)))

这段代码里，stale 不应该出现在第一次列表中，sid 会出现在第一次列表中，但在删除标记提交后也不再出现。注意删除 Cookie 的 Name 和 Path 必须对应原来的 Cookie；如果原 Cookie 带有特定 Domain，删除时也要按同一作用域处理。

按域名与路径核对 Cookie

如果你看到“过期 Cookie 还在”，我建议先不要马上重建 Jar，而是打印目标 URL 和读取结果。很多时候留下的并不是同一个 Cookie，而是同名、不同 Path 的另一条记录。

func printJarCookies(jar http.CookieJar, rawURL string) error {
    // 只查看这个 URL 能发送的 Cookie，不把其他路径的 Cookie 混进判断。
    u, err := url.Parse(rawURL)
    if err != nil {
        return err
    }

    fmt.Printf("URL=%s\\n", u.String())
    for _, cookie := range jar.Cookies(u) {
        fmt.Printf("COOKIE name=%s path=%s value=%s\\n", cookie.Name, cookie.Path, cookie.Value)
    }
    return nil
}

这一步看的是“给这个 URL 会发送什么”，不是 Jar 的完整内部清单。CookieJar 没有公开的全量枚举接口，所以同名 Cookie 的排查必须带上目标 URL。请求 /account 和请求 /，可能得到不同的结果；一个删除标记也可能只覆盖其中一个路径。

从请求前后的列表定位问题

我现在通常把观察点放在三个位置：响应里的 Set-Cookie、调用 jar.Cookies(target) 得到的列表，以及最终请求要访问的 URL。只看其中一个点，很容易把“服务端没有下发删除”误判成“CookieJar 没清理”。

可以把判断结果整理成下面这张小表：

结果示意里把 sid=live 留下来、把 stale=old 标成 expired，是为了体现“读取时过滤”和“主动删除”是两种不同动作。真实项目不要把示意输出当成业务日志，而是把目标 URL、Cookie 名和作用域打印到受控调试日志中。

决定何时重建 Jar

如果只是某个登录接口返回了过期 Cookie，继续复用同一个 Jar 通常没问题；CookieJar 本身会按 Cookie 规则处理后续请求。如果是用户点击退出登录，且会话散落在多个域名、多个 Path 下，我更倾向于明确发送各作用域的删除 Cookie，或者丢弃旧 Jar 并创建新 Jar。

重建 Jar 的代价是所有会话状态都会消失，包括仍然有效的 Cookie。因此它更适合测试隔离、租户切换或“完全退出”这种边界明确的场景，不适合作为每次请求前的清理动作。

常见问题

CookieJar 有直接的 Clear 方法吗？

公开 API 没有提供全量 Clear。可以用匹配作用域的负 MaxAge 删除具体 Cookie；如果要整体清空，重新创建一个 Jar。

为什么服务端返回过期 Cookie，但我还能看到同名 Cookie？

先确认读取的 URL、Domain 和 Path。浏览器或 Jar 中可能同时存在同名但不同作用域的 Cookie，服务端删除其中一条不会自动覆盖其他作用域。

小结

CookieJar 的清理重点不是找一个隐藏的删除函数，而是理解它如何把 Cookie 和目标 URL 联系起来：Expires 负责有效期，负 MaxAge 表达主动删除，Domain 和 Path 决定删除是否命中。排查时同时观察响应、Jar 返回列表和最终请求 URL，通常很快就能判断是过期过滤、作用域不匹配，还是需要重建会话容器。