浏览器不再拦请求:FastAPI 跨域(CORS)配置全解析

前后端分离时代,端口、域名、协议只要有一项不同,就会触发浏览器的「同源策略」拦截。

FastAPI 原生自带 CORSMiddleware,只需几行代码即可让你的 API 被任意前端「安全」调用。本文带你从原理到生产,一次搞定跨域配置。


一、跨域问题的根因:浏览器的同源策略

同源 = 协议 + 域名 + 端口 完全一致

只要三者任一不同,浏览器就会先发一次 预检(OPTIONS)请求 ,再决定是否放行真正的业务请求。

如果服务器未返回正确的 CORS 响应头,请求会被浏览器静默拦截,前端收不到任何数据。


二、FastAPI 的解决思路:官方 CORS 中间件

FastAPI 直接集成了 Starlette 的 CORSMiddleware ,无需额外安装第三方包。

核心方法:在 FastAPI() 实例上注册中间件,指定允许的来源、方法、头部、凭证等参数即可 。


三、最小可运行示例(开发环境秒开)

python 复制代码
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware   # ① 导入

app = FastAPI()

# ② 添加中间件
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*],           # 开发阶段放通所有
    allow_credentials=True,       # 需要 Cookie/Authorization 时设为 True
    allow_methods=["*"],          # 允许全部 HTTP 方法
    allow_headers=["*"],          # 允许全部请求头
)

@app.get("/api/hello")
async def hello():
    return {"msg": "跨域请求成功"}

启动:

bash 复制代码
uvicorn main:app --reload

前端(http://localhost:3000)可直接 fetch("http://localhost:8000/api/hello"),浏览器不再报 CORS 错误 。


四、生产环境:别再用 "*" !精细化配置示例

python 复制代码
origins = [
    "https://app.example.com",   # 正式域名
    "https://admin.example.com",
    "http://localhost:3000",     # 本地开发
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,      # 允许携带 Cookie/Session
    allow_methods=["GET", "POST", "PUT", "DELETE"],  # 按需开放
    allow_headers=["Content-Type", "Authorization", "X-Requested-With"],
    max_age=86400,               # 预检缓存 24h,减少 OPTIONS 次数
)

要点说明

  1. allow_credentials=Trueallow_origins 不能是 ["*"],必须显式列表。
  2. max_age 可让浏览器缓存预检结果,提升性能。
  3. 若使用 HTTPS ,前端地址也必须是 https://,否则浏览器仍拦截。

五、与 Nginx 反向代理的配合(可选)

如果已用 Nginx 统一入口,可在 Nginx 层返回 CORS 头,后端保持关闭 CORS

nginx 复制代码
location /api {
    add_header Access-Control-Allow-Origin $http_origin;
    add_header Access-Control-Allow-Credentials true;
    add_header Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS;
    add_header Access-Control-Allow-Headers Content-Type,Authorization;
    if ($request_method = OPTIONS) { return 204; }  # 预检快速返回
    proxy_pass http://fastapi:8000;
}

优势 :减少后端压力;缺点:多一层配置,需要运维配合。


六、常见报错速查表

前端报错 原因 解决
CORS header 'Access-Control-Allow-Origin' missing 未加中间件或 allow_origins 写错 检查 add_middleware 是否注册
The value of the 'Access-Control-Allow-Origin' header must not be the wildcard * when credentials are true allow_credentials=True 却用 "*" allow_origins 改成具体列表
Request header field x-custom-header is not allowed 不在 allow_headers 白名单 追加自定义 header
OPTIONS 405 Method Not Allowed 预检被后端路由拦截 确保 allow_methods=["*"] 或包含 OPTIONS

七、总结:三步口诀

  1. 开发allow_origins=["*"] 先跑通
  2. 测试 :逐项收紧,显式域名 + 最小方法 + 最小头部
  3. 上线credentials=True 务必配具体域名,拒绝 "*"

记住:CORS 配置不是越多越好,而是越精准越安全。

照着本文模板,10 分钟即可让你的 FastAPI 服务与前端「跨域无阻碍」联调上线 。

相关推荐
Cherry Zack4 天前
FastAPI 入门指南 :基础概念与核心特性
开发语言·python·fastapi·1024程序员节
深兰科技4 天前
深兰科技法务大模型亮相,推动律所文书处理智能化
人工智能·scrapy·beautifulsoup·scikit-learn·pyqt·fastapi·深兰科技
钱彬 (Qian Bin)6 天前
项目实践4—全球证件智能识别系统(Qt客户端开发+FastAPI后端人工智能服务开发)
人工智能·qt·fastapi
钱彬 (Qian Bin)6 天前
项目实践3—全球证件智能识别系统(Qt客户端开发+FastAPI后端人工智能服务开发)
人工智能·qt·fastapi
后台开发者Ethan6 天前
FastAPI之 Python的类型提示
python·fastapi·ai编程
刘逸潇20056 天前
中间件与CORS(基于fastapi)
中间件·fastapi
蓝倾7 天前
小红书item_get接口JSON数据解析指南
api·fastapi
刘逸潇20058 天前
jinji2模板
fastapi
onelafite9 天前
怎么获取小红书用户笔记作品列表?item_search_shop_videoAPI接口指南
api·fastapi