proxy_cookie_domain用于修正Set-Cookie的domain值以匹配前端域名,proxy_cookie_path调整path,二者须配合SameSite=None、Secure及CORS凭据配置才生效。

核心是用 proxy_cookie_domain 修正 Cookie 的 domain 值,再用 proxy_cookie_path 调整 path,两者必须配合 SameSite、Secure 等属性才真正生效。
先修 domain:让 Cookie 能被前端域名接受
后端返回的 Set-Cookie 如果带 Domain=backend.com 或留空(默认为后端 Host),而用户实际访问的是 app.example.com,浏览器会直接丢弃这个 Cookie。proxy_cookie_domain 就是干这个的:
- 写法要带正则匹配源 domain,比如 proxy_cookie_domain ~\.?backend\.com ".example.com"; —— 开头的点和引号表示允许所有子域共享
- 不能写成 proxy_cookie_domain localhost example.com;,因为 localhost 不在 Set-Cookie 的 Domain 字段里,规则根本不会触发
- 指令必须放在 location 块内,且在 proxy_pass 之后,否则不生效
再调 path:确保 Cookie 在正确路径下自动携带
后端常设 Path=/api 或 Path=/sub/,但前端请求的是 /,浏览器只在匹配路径下才发 Cookie。proxy_cookie_path 在响应发出前重写 Path 字段:
- 若后端返回 Path=/api,前端访问根路径,就加 proxy_cookie_path /api /;
- 若代理路径带前缀(如 location /app/ { proxy_pass http://backend/; }),后端通常返回 Path=/,这时需补上前缀:proxy_cookie_path / /app/;
- 支持正则,比如把 /v1/user 替成 /user:proxy_cookie_path ~^/v1/(.*)$ /$1;
补全关键属性:SameSite 和 Secure 缺一不可
Chrome 80+ 要求跨站 Cookie 必须显式声明 SameSite=None 和 Secure(HTTPS 下):
- 后端没设,Nginx 可用 proxy_cookie_path 补全:proxy_cookie_path / "/; Path=/; HttpOnly; Secure; SameSite=None";
- 如果用 proxy_cookie_domain 单独改 domain,但没同步处理 SameSite 和 Secure,Cookie 仍会被浏览器静默拒绝
- Secure 属性必须与前端协议一致:前端走 HTTPS,后端或 Nginx 就必须加 Secure;HTTP 环境不能加,否则 Cookie 写不进
配套基础设置不能漏
光靠 cookie 指令还不够,这些也得配齐:
- Access-Control-Allow-Origin 不能是 *,必须是具体前端域名,比如 add_header 'Access-Control-Allow-Origin' 'https://app.example.com' always;
- Access-Control-Allow-Credentials 必须为 true:add_header 'Access-Control-Allow-Credentials' 'true' always;
- 前端请求必须带 credentials:fetch('/api/login', { credentials: 'include' })
- proxy_pass 推荐用 HTTPS 后端地址,避免中间降级导致 Secure 失效


















