本文详解因前端与后端域名不一致（如 localhost 与 127.0.0.1）导致 Cookie 无法跨请求传递的根本原因，并提供可落地的解决方案，涵盖 FastAPI 后端配置、Fetch 前端调用规范及开发环境最佳实践。
本文详解因前端与后端域名不一致（如 `localhost` 与 `127.0.0.1`）导致 cookie 无法跨请求传递的根本原因，并提供可落地的解决方案，涵盖 fastapi 后端配置、fetch 前端调用规范及开发环境最佳实践。
在构建多步骤注册流程时，常见场景是：前端通过 fetch 发送第一步请求 → 后端（如 FastAPI）设置含唯一 ID 的 Cookie → 第二步请求需自动携带该 Cookie 以维持会话状态。但若第二步请求中 Cookie 未出现在请求头（Cookie 字段缺失），且开发者工具的 Application → Cookies 面板中也为空，问题往往并非代码逻辑错误，而是被忽略的关键前提：同源策略（Same-Origin Policy）对 Cookie 的严格限制。
? 核心原因：localhost 与 127.0.0.1 被视为不同源
尽管二者在语义上等价，但浏览器将 http://localhost:8000 和 http://127.0.0.1:8000 视为完全不同的源（origin）。根据 RFC 6265，Cookie 的 Domain 属性默认绑定到响应时的完整主机名。当后端运行在 127.0.0.1 并返回 Set-Cookie，而前端页面由 localhost 加载时，浏览器拒绝将该 Cookie 关联到 localhost 发起的后续请求——因此既不存储，也不发送。
✅ 正确解决方案（三步到位）
1. 统一开发环境访问域名
✅ 推荐做法：始终使用 localhost 访问前后端（例如 http://localhost:3000 前端 + http://localhost:8000 后端）。
❌ 避免混用：http://localhost:3000 + http://127.0.0.1:8000 或 http://127.0.0.1:3000 + http://localhost:8000。
? 提示：修改 /etc/hosts（macOS/Linux）或 C:\Windows\System32\drivers\etc\hosts（Windows），添加 127.0.0.1 localhost 确保解析稳定；开发服务器启动时明确指定 --host=localhost。
2. FastAPI 后端：正确设置 Cookie 属性
确保 set_cookie 显式声明 domain 和 samesite，尤其在开发阶段：
from fastapi import Response
@app.post("/register/step1")
def step1(username: str, password: str, response: Response):
unique_id = generate_session_id()
response.set_cookie(
key="session_id",
value=unique_id,
httponly=True, # 防 XSS
secure=False, # 开发环境设为 False（HTTPS 时设 True）
samesite="lax", # 兼容跨站 POST（如表单提交）
domain="localhost", # 关键！显式指定 domain
max_age=3600 # 1 小时过期
)
return {"status": "success", "id": unique_id}
⚠️ 注意：domain="localhost" 是必须项。若省略，浏览器可能默认设为 127.0.0.1，导致 localhost 页面无法读取。
3. 前端 Fetch：确保 credentials: 'include' 且无跨域干扰
你的代码中已正确使用 credentials: 'include'，这是必要条件。但需确认：
- 请求 URL 必须与当前页面同源（即都用 localhost）；
- 若存在反向代理（如 Nginx），需透传 Set-Cookie 头并设置 SameSite=None; Secure（仅生产 HTTPS 环境）；
- 避免在 headers 中手动设置 Cookie 字段（浏览器自动注入，手动设置会被忽略）。
// ✅ 正确：同源 + include credentials
fetch("http://localhost:8000/register/step2", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include", // ← 必须存在
body: JSON.stringify({ email_code: "123456" })
});
? 验证与调试技巧
- 打开浏览器开发者工具 → Application → Cookies，检查 localhost 下是否有对应 Cookie；
- 在 Network → 请求详情 → Headers 中查看 Request Headers 是否含 Cookie: session_id=xxx；
- 使用 document.cookie 在控制台验证 JS 是否可读取（注意 HttpOnly Cookie 不可见）；
- 后端日志打印 request.cookies.get("session_id")，确认服务端是否收到。
? 总结
Cookie 丢失的“隐形杀手”往往是开发环境的域名不一致。统一使用 localhost、显式设置 domain="localhost"、坚持 credentials: 'include'，三者缺一不可。切勿依赖 127.0.0.1 与 localhost 的等价性——浏览器不认这个逻辑。上线前务必切换至 HTTPS 并调整 secure=True 与 samesite="strict" 以提升安全性。
