WebSocket 握手响应中正确设置 Set-Cookie 头的完整实践指南-Golang-PHP中文网

WebSocket 握手响应中正确设置 Set-Cookie 头的完整实践指南

在 WebSocket 握手阶段（HTTP Upgrade 响应）中，无法通过标准 http.SetCookie() 设置 Cookie，因为 Gorilla 或 x/net/websocket 的 Upgrade 过程会劫持连接、清空响应头；必须在 Upgrader 配置中显式注入 Set-Cookie 头字段。

在 websocket 握手阶段（http upgrade 响应）中，无法通过标准 `http.setcookie()` 设置 cookie，因为 gorilla 或 `x/net/websocket` 的 upgrade 过程会劫持连接、清空响应头；必须在 upgrader 配置中显式注入 `set-cookie` 头字段。

WebSocket 协议（RFC 6455）明确允许在 101 Switching Protocols 响应中包含任意合法 HTTP 头，包括 Set-Cookie。但实践中，绝大多数 WebSocket 服务库（尤其是 gorilla/websocket 和已归档的 golang.org/x/net/websocket）会在执行 Upgrade 操作时调用底层 http.Hijack()，导致 ResponseWriter 的 header 缓冲区被丢弃或忽略——因此你在 Upgrade() 之前调用 http.SetCookie() 是无效的。

✅ 正确做法：通过 Upgrader 配置注入 Set-Cookie

以当前 Go 生态事实标准 github.com/gorilla/websocket 为例（强烈推荐替代已废弃的 x/net/websocket），其 Upgrader 提供了 WriteHandshake 钩子和 CheckOrigin 等扩展点，但最直接、可靠的方式是利用 Upgrader 的 Subprotocols 和 CheckOrigin 之外的隐藏能力：通过 Upgrader.Header 函数动态写入响应头。

⚠️ 注意：Upgrader.Header 是一个函数类型 func(http.ResponseWriter, *http.Request) http.Header，它在握手响应写入前被调用，返回的 http.Header 将被合并进最终响应头。

以下是生产就绪的实现示例：

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/gorilla/websocket"
)

var upgrader = websocket.Upgrader{
    // 允许跨域（如需）——务必配合前端 credentials: true
    CheckOrigin: func(r *http.Request) bool {
        return true // 生产环境请严格校验 Origin
    },
    // ✅ 关键：在握手响应中注入 Set-Cookie
    Header: func(w http.ResponseWriter, r *http.Request) http.Header {
        // 构建 Cookie（注意：Secure=true 仅限 HTTPS 环境）
        cookie := &http.Cookie{
            Name:     "_c_id_",
            Value:    "abcd",
            Path:     "/",
            HttpOnly: true,
            Secure:   false, // 开发环境可设 false；生产 HTTPS 必须为 true
            MaxAge:   3600,  // 1 小时有效期
            SameSite: http.SameSiteLaxMode,
        }
        w.Header().Set("Set-Cookie", cookie.String())
        return w.Header()
    },
}

func wsHandler(w http.ResponseWriter, r *http.Request) {
    conn, err := upgrader.Upgrade(w, r, nil)
    if err != nil {
        log.Printf("WebSocket upgrade error: %v", err)
        return
    }
    defer conn.Close()

    // 示例：简单回显
    for {
        _, msg, err := conn.ReadMessage()
        if err != nil {
            log.Printf("Read error: %v", err)
            break
        }
        if err := conn.WriteMessage(websocket.TextMessage, msg); err != nil {
            log.Printf("Write error: %v", err)
            break
        }
    }
}

func main() {
    http.HandleFunc("/v2", wsHandler)
    log.Println("Server starting on :8080...")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

? 为什么原代码失败？

你使用的 golang.org/x/net/websocket 已于 2022 年正式归档（官方说明），其 websocket.Server.ServeHTTP 内部会：

NotebookLM CLI Cookies

使用 nlm CLI 检索并回答已上传至 NotebookLM 的文档问题。适用于用户需要查找信息、总结来源或查询特定笔记本时。

下载

调用 w.WriteHeader(101) 并立即写入固定握手头（Upgrade, Connection, Sec-WebSocket-Accept 等）；
忽略 w.Header() 中此前设置的任何内容（包括 Set-Cookie）；
最终 http.SetCookie() 写入的 header 被完全丢弃。

而 gorilla/websocket.Upgrader 显式支持 Header 回调，正是为这类定制化响应头（如认证凭证、追踪 ID、会话 Cookie）设计的标准化入口。

? 重要注意事项

浏览器限制：即使服务端成功发送 Set-Cookie，现代浏览器不会在 WebSocket 握手响应中保存该 Cookie（Chrome bug #975128 等长期存在）。这意味着：
✅ 服务端可借此传递状态（如初始化 session）；
❌ 但客户端 JS 无法通过 document.cookie 读取它，也不能用于后续普通 HTTP 请求的自动携带（除非同源且由页面初始请求设置）。
→ 实际场景中，Set-Cookie 在握手中的主要用途是：服务端绑定连接与用户会话（如生成并写入 session ID），而非供前端 JS 消费。
安全性强制要求：若使用 Secure: true，必须确保 WebSocket 使用 wss:// 协议，否则浏览器拒绝发送 Cookie；同时建议启用 HttpOnly + SameSite=Lax 防范 XSS 和 CSRF。
避免并发写 panic：每个 *websocket.Conn 必须保证 写操作串行化（例如通过 chan []byte 写队列），否则 WriteMessage 并发调用将触发 concurrent write to connection panic。
超时与健壮性：务必在连接建立后立即设置读/写 deadline（如 conn.SetReadDeadline(time.Now().Add(30*time.Second))），防止因网络异常导致 goroutine 泄漏。

✅ 总结

场景	推荐方案
✅ 设置握手响应中的 Set-Cookie	使用 gorilla/websocket.Upgrader.Header 回调，手动构造并写入 Set-Cookie 字符串
❌ 使用 http.SetCookie()	无效——Upgrade 过程劫持连接，header 被清空
⚠️ 浏览器是否保存该 Cookie	否（规范未要求，主流浏览器不支持），仅服务端可用
? 替代方案（更推荐）	将鉴权逻辑前移至握手前：校验请求 Cookie/JWT，验证通过后再 Upgrade（见文首鉴权示例）

遵循以上模式，即可在符合 RFC 的前提下，安全、可靠地在 WebSocket 握手阶段注入状态信息，为无状态长连接赋予会话上下文能力。