本文详解因 localhost 与 127.0.0.1 被浏览器视为不同源而导致 cookie 无法存储和自动携带的问题，涵盖 fetch 的 credentials 设置、后端 cookie 属性配置（如 samesite、secure）、以及开发环境统一域名的实践方案。
本文详解因 localhost 与 127.0.0.1 被浏览器视为不同源而导致 cookie 无法存储和自动携带的问题，涵盖 fetch 的 credentials 设置、后端 cookie 属性配置（如 samesite、secure）、以及开发环境统一域名的实践方案。
在构建多步骤注册流程时，前端通过 fetch 发起请求、后端通过 Set-Cookie 响应头下发会话标识（如唯一 ID），是常见的状态保持方式。但若后续请求未携带该 Cookie，常见原因并非代码逻辑错误，而是浏览器同源策略与 Cookie 作用域规则的隐性限制。
✅ 关键前提：Fetch 必须启用凭据模式
你已在代码中正确设置了 credentials: 'include'——这是必要条件，否则浏览器默认不会发送 Cookie。但仅此一项远远不够：
fetch("/register/step2", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include", // ✅ 必须存在且值为 'include'
body: JSON.stringify({ email_code: code })
});
⚠️ 注意：若 credentials: "include" 与 mode: "no-cors" 共存，将直接报错；同时，服务端响应必须明确允许凭据（见下文 CORS 配置）。
❌ 根本原因：localhost ≠ 127.0.0.1
正如问题答案所揭示——浏览器将 http://localhost:8000 和 http://127.0.0.1:8000 视为两个完全不同的源（origin）。Cookie 的 domain 属性默认绑定到响应时的 Host，若后端运行在 127.0.0.1:8000，而前端页面由 http://localhost:3000 加载，则 Cookie 不会被关联到 localhost 页面，自然不会在后续请求中自动发送，也不会出现在 DevTools 的「Application → Cookies」列表中。
✅ 正确解决方案（三步走）
1. 统一开发环境访问域名
✅ 推荐做法：全部使用 localhost
- 后端启动时绑定 localhost（而非 127.0.0.1）：
uvicorn main:app --host localhost --port 8000
- 前端通过 http://localhost:3000 访问（而非 http://127.0.0.1:3000）
2. 后端设置兼容的 Cookie 属性（FastAPI 示例）
确保 Set-Cookie 响应头显式声明 domain 和 SameSite，避免浏览器因安全策略拒绝存储：
from fastapi import Response
@app.post("/register/step1")
def step1(username: str, password: str):
unique_id = generate_session_id()
response = JSONResponse(content={"status": "success"})
# 显式设置 domain 为 localhost（注意：不能设为 127.0.0.1）
response.set_cookie(
key="session_id",
value=unique_id,
httponly=True,
secure=False, # 开发环境可设 False；生产环境必须 True + HTTPS
samesite="Lax", # 推荐 Lax；若需跨站 POST 携带，可设 None（但需同时设 secure=True）
domain="localhost", # ✅ 关键！明确指定 domain
max_age=3600
)
return response
? 补充说明：domain="localhost" 是合法的；但 domain="127.0.0.1" 在部分浏览器中可能被忽略（因 IP 地址不支持二级域名匹配）。
3. 确保 CORS 配置允许凭据
FastAPI 中需启用 allow_credentials=True，并显式指定 allow_origins（不可用 ["*"]）：
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000"], # ✅ 精确指定前端地址
allow_credentials=True, # ✅ 必须为 True 才能接受 credentials: 'include'
allow_methods=["*"],
allow_headers=["*"],
)
? 验证与调试技巧
- 在 Firefox/Chrome DevTools 中，检查「Network → 请求详情 → Headers → Request Headers」是否含 Cookie: session_id=xxx；
- 查看「Application → Storage → Cookies」，确认 Cookie 出现在 localhost（而非 127.0.0.1）条目下；
- 若仍失败，临时在响应头中添加 Set-Cookie: test=1; Domain=localhost; Path=/; SameSite=Lax 手动验证基础链路。
✅ 总结
Cookie 跨请求失效，90% 源于源不一致（localhost vs 127.0.0.1）或后端 Cookie 属性缺失（未设 domain/SameSite）。务必统一开发域名、显式配置 Cookie 属性、并配对启用 credentials: 'include' 与 allow_credentials=True。切勿依赖“看起来一样”的 IP 和域名——浏览器的同源判定严格且不容妥协。
