FastAPI怎么设置Cookie和读取Cookie-Python教程-PHP中文网

FastAPI设置Cookie需用response.set_cookie()并注意secure、samesite、path等参数；读取Cookie须用Cookie依赖注入，参数名须与key一致。跨域时需samesite="none"配secure=True、credentials: "include"及CORS allow_credentials=True。

fastapi怎么设置cookie和读取cookie

FastAPI 设置和读取 Cookie 的核心就两件事：用 response.set_cookie() 发送，用 Cookie 依赖注入接收。但漏掉 secure=True、samesite 或路径不匹配，Cookie 就可能不生效或被浏览器丢弃。

怎么用 response.set_cookie() 设置 Cookie

必须通过 Response 对象调用 set_cookie()，不能直接 return 字典后“顺带”加 Cookie —— FastAPI 不会自动提取。

推荐在路径函数中声明 response: Response 参数，然后调用 response.set_cookie()；返回值仍可写普通 dict 或 Pydantic 模型，FastAPI 会自动把 Cookie 注入最终响应
如果直接返回 JSONResponse 等响应类实例，必须手动调用它的 set_cookie() 方法，且确保内容已序列化为 JSON 兼容类型
关键参数别漏：secure=True（HTTPS 环境下强制要求）、httponly=True（防 XSS）、samesite="lax"（默认较安全，跨域场景需设 "none" 并配 secure=True）
path 默认是 "/"，但如果前端只在 /admin 下发请求，却把 Cookie 种在 path="/api"，浏览器根本不会携带

示例：

from fastapi import FastAPI, Response
app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        max_age=3600,
        secure=True,
        httponly=True,
        samesite="lax",
        path="/"
    )
    return {"status": "logged in"}

怎么用 Cookie 依赖读取客户端传来的 Cookie

必须显式用 Cookie 类声明参数，否则 FastAPI 会把它当查询参数处理 —— 即使请求头里有 Cookie: session_id=abc123，session_id: str 这样写也收不到。

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

参数名（如 session_id）必须和 Cookie 的 key 完全一致，大小写敏感
用 Cookie(default=None) 表示可选；用 Cookie() 无默认值则该 Cookie 缺失时返回 422 错误
支持 Pydantic 校验，比如 session_id: str = Cookie(min_length=10)，非法值直接 422
注意：Swagger UI（/docs）用 JavaScript 发请求，无法携带 Cookie，测试要用 curl 或 Postman 手动加 -b "session_id=abc123"

示例：

from fastapi import FastAPI, Cookie
app = FastAPI()

@app.get("/profile")
def get_profile(session_id: str = Cookie(None)):
    if not session_id:
        return {"error": "missing session_id cookie"}
    return {"session_id": session_id}

跨域场景下 Cookie 不生效的常见原因

前后端分离（如 Vue 前端跑在 http://localhost:5173，FastAPI 后端在 http://localhost:8000）时，Cookie 默认被浏览器拦截。

samesite="none" 必须搭配 secure=True，否则现代浏览器（Chrome 80+）直接拒绝设置
前端 fetch 必须带 credentials: "include"，否则浏览器不发送 Cookie
FastAPI 的 CORS 中必须启用 allow_credentials=True，且 allow_origins 不能为 ["*"]（必须指定具体域名）
如果后端部署在子域（如 api.example.com），而 Cookie 的 domain 设为 example.com，需显式指定 domain=".example.com"（注意开头的点）

容易被忽略的细节

Cookie 不是“设了就一定能读”，很多问题出在路径、域、协议或浏览器策略上。

max_age=0 或负数会让浏览器立刻删除 Cookie，调试时别误写
expires 和 max_age 二选一即可，同时设时以 max_age 为准（Starlette 行为）
使用 Response 参数方式时，即使你 return 一个空 dict，response.set_cookie() 依然生效；但若 return Response 实例，就得自己负责全部响应逻辑
本地开发 HTTP 环境下，secure=True 会导致 Cookie 根本不发送 —— 测试时先设为 False，上线前务必改回 True