在 nginx 中，默认配置下 `proxy_set_header` 不会自动将客户端的 cookie 传递给后端服务器。要实现这一功能，需要显式地添加一条指令，将 nginx 内置变量 `$http_cookie` 的值赋给后端的 `cookie` 请求头。具体做法是在 `location` 或 `server` 块中加入 `proxy_set_header cookie $http_cookie;`，这样 nginx 就会把客户端发来的原始 cookie 完整转发给后端应用。
为什么默认情况下 Cookie 不会被传递？
Nginx 作为反向代理时，为了保持 HTTP 协议的规范性和安全性，默认只透传部分特定的请求头，如 `Host`、`Connection` 和 `User-Agent`。Cookie 数据通常包含敏感信息或会话状态，且体积可能较大，因此未被列入默认透传列表。如果后端服务依赖 Cookie 进行身份验证或状态维持，而 Nginx 没有显式配置转发，后端收到的请求头中将缺失 `Cookie` 字段，导致会话失效或鉴权失败。理解这一默认行为有助于排查为何后端无法读取客户端的登录状态。
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://backend_server;
# 默认透传的头部
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# 关键配置：手动传递 Cookie
proxy_set_header Cookie $http_cookie;
}
}
上述配置展示了标准的 Nginx 反向代理设置。其中 `proxy_pass` 指向后端服务，`proxy_set_header Host` 确保后端知道原始请求的目标主机。最关键的一行是 `proxy_set_header Cookie $http_cookie;`。这里 `$http_cookie` 是 Nginx 的内置变量，它自动收集客户端请求中所有的 Cookie 字段，并将其拼接成一个字符串，格式为 `name1=value1; name2=value2`。通过这行配置，Nginx 会在将请求转发给后端之前，插入一个名为 `Cookie` 的请求头，其值即为客户端发送的原始 Cookie 内容。重启 Nginx 或重新加载配置后，后端即可接收到完整的 Cookie 信息。
如何处理多个 Cookie 或特定 Cookie 的过滤？
有时我们可能不需要传递所有 Cookie，或者希望合并来自不同来源的 Cookie。Nginx 提供了灵活的变量处理能力来实现这些需求。例如，可以使用 `map` 指令或直接在 `proxy_set_header` 中使用表达式来筛选特定的 Cookie。如果后端只需要某个特定的会话 ID，可以提取 `$http_cookie` 中包含该 ID 的部分，或者使用更复杂的逻辑构建新的 Cookie 头。此外，还可以结合 `if` 指令（尽管官方不推荐在 location 中使用 if）或 Lua 模块进行更精细的控制，但在大多数标准场景下，直接传递全部 Cookie 是最简单且通用的做法。需要注意的是，如果客户端发送了空的 Cookie，`$http_cookie` 变量将为空，此时 Nginx 仍然会发送一个空的 `Cookie` 头，这通常不会影响后端处理，但某些严格的后端实现可能会忽略空头。
# 示例：仅传递名为 session_id 的 Cookie
# 注意：Nginx 原生不支持直接解析 Cookie 键值对，
# 通常需要借助 Lua 或 Perl 模块，或者在后端处理。
# 这里展示的是标准 Nginx 的做法，即传递全部 Cookie。
# 如果需要过滤，建议在后端代码中根据 Session ID 获取其他信息。
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://backend_server;
proxy_set_header Host $host;
# 传递所有 Cookie
proxy_set_header Cookie $http_cookie;
# 如果需要传递额外的自定义头
proxy_set_header X-Custom-Header "value";
}
}
在实际应用中，绝大多数情况直接使用 `$http_cookie` 传递所有 Cookie 即可满足需求。后端应用通常会解析这个字符串，提取所需的会话标识符。如果确实需要过滤，由于 Nginx 原生配置语言对字符串解析能力有限，通常建议在应用层处理。例如，后端收到所有 Cookie 后，只读取 `session_id`，忽略其他无关的追踪或分析 Cookie。这种设计既保证了 Nginx 配置的简洁性，又赋予了后端更大的灵活性。同时，要注意 Cookie 的大小限制，HTTP 请求头总大小通常受限于 Nginx 和后端服务器的配置，过大的 Cookie 可能导致请求被截断或拒绝，此时应考虑使用其他机制存储大型数据，如数据库或缓存，并在 Cookie 中仅保留引用 ID。
基于 proxy_set_header Cookie 配置的具体问题排查
当配置了 `proxy_set_header Cookie $http_cookie;` 后，如果后端仍然收不到 Cookie，最常见的原因是配置未生效或存在覆盖。首先检查 Nginx 配置文件语法是否正确，使用 `nginx -t` 测试配置，然后重新加载 `nginx -s reload`。其次，确认该指令位于正确的 `location` 块内，且没有被后续的 `proxy_set_header` 指令覆盖。Nginx 的 `proxy_set_header` 指令是追加式的，但如果多次设置同一个头，后面的会覆盖前面的。确保没有其他地方意外清空了 `Cookie` 头。另外，检查后端应用是否正确解析了请求头，有些框架可能需要特定的中间件来处理 Cookie。最后，使用浏览器开发者工具或 `curl -v` 命令查看实际发出的 HTTP 请求，确认 `Cookie` 头是否存在于发送给 Nginx 的请求中，以及 Nginx 转发给后端的请求中是否包含了该头。通过逐层排查，可以快速定位并解决 Cookie 传递失败的问题。
