本文详解 fastapi 中 cors 配置的核心要点，涵盖预检请求（options）处理、常见错误排查、安全配置建议及完整可运行示例，助你快速解决 react 前端调用 fastapi 后端时的跨域拦截问题。
本文详解 fastapi 中 cors 配置的核心要点，涵盖预检请求（options）处理、常见错误排查、安全配置建议及完整可运行示例，助你快速解决 react 前端调用 fastapi 后端时的跨域拦截问题。
在前后端分离开发中，当 React 应用（http://localhost:3000）向 FastAPI 后端（http://localhost:8000）发起 POST 请求时，浏览器会因同源策略触发 CORS 预检（preflight）机制——先发送一个 OPTIONS 请求验证权限。若后端未正确响应预检，就会出现典型错误：
Access to fetch at 'http://localhost:8000/predict/' from origin 'http://localhost:3000' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present...
该错误并非前端代码缺陷，而是后端 CORS 中间件未生效或配置未覆盖实际请求场景所致。以下为系统性解决方案。
✅ 正确配置 FastAPI 的 CORS 中间件
FastAPI 通过 CORSMiddleware 自动拦截并响应 OPTIONS 预检请求。关键在于注册顺序与参数语义：中间件必须在 app = FastAPI() 实例化之后、任何路由定义之前添加，且参数需严格匹配前端行为。
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
✅ 推荐配置（开发环境）
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# 允许的前端源 —— 必须精确匹配协议+域名+端口
origins = [
"http://localhost:3000", # React 开发服务器（Vite/CRAC）
"http://127.0.0.1:3000", # 部分系统可能解析为 127.0.0.1
]
app.add_middleware(
CORSMiddleware,
allow_origins=origins, # ⚠️ 不要写成 ["*"] + allow_credentials=True（冲突！）
allow_credentials=True, # 若前端使用 credentials: 'include'，此项必须为 True
allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"], # 显式声明更安全
allow_headers=["Content-Type", "Authorization", "X-Requested-With"], # 避免 "*"
)? 为什么
allow_headers=["*"]在allow_credentials=True时会失败？
浏览器规范明确禁止：当Access-Control-Allow-Credentials: true时，Access-Control-Allow-Headers不可为通配符*，否则预检直接被拒绝。应显式列出所需 Header（如Content-Type是 POST JSON 必需）。
✅ 生产环境加固建议
# 生产环境禁用通配符，使用正则匹配多子域（需 allow_origin_regex）
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origin_regex=r"https://.*\.yourcompany\.com", # 如 app.yourcompany.com, api.yourcompany.com
allow_credentials=False, # 生产中慎用 credentials，优先用 Bearer Token
allow_methods=["GET", "POST"],
allow_headers=["Content-Type", "Authorization"],
)? 常见陷阱与调试技巧
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
OPTIONS 请求返回 404 |
CORSMiddleware 未注册，或注册位置错误（如在 @app.get() 之后） |
确保 app.add_middleware(...) 紧跟 app = FastAPI()，且无条件执行 |
控制台报 No 'Access-Control-Allow-Origin' 即使配置了 allow_origins
|
allow_origins 值不匹配前端 Origin 头（如前端是 http://localhost:3000，但配置了 http://127.0.0.1:3000） |
使用浏览器 DevTools → Network → 查看请求的 Origin 值，并精确复制到 origins 列表 |
fetch 报错 Failed to fetch 且无 CORS 提示 |
后端崩溃（如 Pydantic 模型校验失败）、Uvicorn 进程异常或端口被占用 | 检查 Uvicorn 日志；运行 netstat -ano \| findstr :8000（Windows）或 lsof -i :8000（macOS/Linux）释放端口；确保 uvicorn main:app 中模块名与文件名一致（如 maintest.py → uvicorn maintest:app） |
? 题中“改端口后解决”的真相：
日志显示Attribute "app" not found in module "maintest"，说明 Uvicorn 启动时找不到app实例——根本原因是文件名/模块名不匹配或代码未保存。所谓“改端口”只是触发了进程重启，掩盖了真实问题。务必确保：
- Python 文件（如
main.py）中存在app = FastAPI()；- 启动命令
uvicorn main:app中的main与文件名一致；- 无语法错误导致模块导入失败。
✅ 完整可验证示例（含前端 fetch）
后端 main.py：
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
app = FastAPI()
class InputData(BaseModel):
mean_radius: float
mean_texture: float
origins = ["http://localhost:3000"]
app.add_middleware(
CORSMiddleware,
allow_origins=origins,
allow_credentials=True,
allow_methods=["POST"],
allow_headers=["Content-Type"],
)
@app.post("/predict/")
def predict(data: InputData):
return {"prediction": round(data.mean_radius * data.mean_texture, 2)}前端 fetch 调用（React）：
// 注意：credentials: 'include' 必须与后端 allow_credentials=True 匹配
const response = await fetch("http://localhost:8000/predict/", {
method: "POST",
credentials: "include", // 或移除此项（默认 omit），后端则设 allow_credentials=False
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ mean_radius: 10.5, mean_texture: 20.3 }),
});✅ 总结：三步构建可靠跨域通信
-
精准配置
allow_origins：开发期列出所有前端地址，生产期用正则或白名单； -
匹配凭据策略：前端
credentials与后端allow_credentials必须一致，且allow_headers不可用*； -
验证中间件生效：启动后检查 Uvicorn 日志是否输出
Application startup complete，并在浏览器 Network 面板确认OPTIONS请求返回 200 及Access-Control-Allow-*头。
遵循以上实践，即可彻底规避 CORS 阻塞，让 React 与 FastAPI 的协作稳定、安全、可维护。
