本文详解因 localhost 与 127.0.0.1 被浏览器视为不同源而导致 cookie 无法存储和自动携带的问题，涵盖前端 fetch 配置、后端响应头设置及开发环境统一域名的关键实践。
本文详解因 localhost 与 127.0.0.1 被浏览器视为不同源而导致 cookie 无法存储和自动携带的问题，涵盖前端 fetch 配置、后端响应头设置及开发环境统一域名的关键实践。
在构建多步骤注册流程（如 FastAPI 后端 + 纯 JavaScript 前端）时，常见一种“Cookie 丢失”现象：服务端成功通过 Set-Cookie 响应头下发 Cookie（DevTools Network 面板可见），但后续请求中该 Cookie 却未出现在请求头，也不显示在 Storage → Cookies 标签页下——导致状态无法延续。根本原因往往并非代码逻辑错误，而是浏览器同源策略对 Cookie 的严格域匹配机制。
? 关键原因：localhost ≠ 127.0.0.1
尽管两者均指向本地回环地址，但浏览器（Chrome、Firefox、Safari）将 http://localhost:8000 和 http://127.0.0.1:8000 视为完全不同的源（origin）。Cookie 默认具有 Domain 属性，若服务端未显式指定 Domain，浏览器会自动将其绑定到响应来源的完整主机名。因此：
- 若前端页面在 http://localhost:3000 加载，
- 后端 API 返回 Set-Cookie: session_id=abc123; Path=/（无 Domain），
- 浏览器仅允许该 Cookie 在 localhost 下发送，拒绝在 127.0.0.1 请求中携带，反之亦然。
这正是你遇到问题的核心：前端访问 localhost，而 fetch 请求发往 127.0.0.1（或反之），导致 Cookie 被隔离。
✅ 正确解决方案
1. 统一开发环境域名（推荐）
- 前端始终用 http://localhost:3000 访问；
- 后端服务也绑定到 localhost（如 FastAPI 启动时指定 --host localhost 或 --host 0.0.0.0，并通过 localhost:8000 调用）；
- ✅ 优势：无需修改 Cookie 设置，符合默认行为，最安全可靠。
2. 显式设置 Cookie 的 Domain（备选）
若必须使用 127.0.0.1，可在 FastAPI 中显式指定 Domain，使其兼容 localhost：
from fastapi import Response
@app.post("/register/step1")
def step1(username: str, password: str):
unique_id = generate_id()
response = Response(content="OK")
# 关键：显式设置 Domain 为 localhost（注意：不能设为 127.0.0.1！）
response.set_cookie(
key="registration_id",
value=unique_id,
httponly=True,
secure=False, # 开发环境可设 False；生产务必 True + HTTPS
samesite="Lax", # 推荐 Lax，兼顾安全性与跨站 POST 兼容性
domain="localhost", # ← 强制绑定到 localhost
path="/",
max_age=3600
)
return response
⚠️ 注意：domain="localhost" 是合法值；但 domain="127.0.0.1" 无效且会被浏览器忽略（RFC 6265 明确禁止 IP 地址作为 Cookie Domain）。
3. 前端 fetch 必须启用 credentials
你已正确添加 credentials: 'include' —— 这是必要前提，确保浏览器在跨源（但同域）请求中自动附带 Cookie：
fetch("/register/step2", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include", // ✅ 已正确配置
body: JSON.stringify({ email_code: code })
});
? 补充：若 API 部署在不同端口（如前端 localhost:3000，后端 localhost:8000），需确保后端 CORS 配置允许凭据：
from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["http://localhost:3000"], allow_credentials=True, # ← 必须为 True allow_methods=["*"], allow_headers=["*"], )
? 验证与调试技巧
- 打开浏览器 DevTools → Application → Cookies，确认目标域名（如 localhost）下存在对应 Cookie；
- 检查 Network → 请求的 Request Headers 中是否含 Cookie: registration_id=xxx；
- 查看响应头 Set-Cookie 是否包含 Domain=localhost; Path=/; HttpOnly; SameSite=Lax；
- 使用 document.cookie 在控制台检查当前页面可读取的 Cookie（注意：HttpOnly Cookie 不可被 JS 读取，但会自动发送）。
✅ 总结
Cookie 丢失问题 90% 源于域名不一致。优先统一使用 localhost 作为开发域名，避免 127.0.0.1；其次确保后端 Set-Cookie 正确设置 domain="localhost"（非 IP）、samesite 和 secure 属性，并配合前端 credentials: 'include' 与后端 CORS 凭据支持。遵循此三步，多步骤状态管理即可稳定运行。
