要解决 TypeScript 前端在浏览器里调用本地 FastAPI 模型服务时的跨域拦截,需要在 FastAPI 应用上挂载 CORSMiddleware,并让浏览器发起的 OPTIONS 预检请求拿到明确的允许响应头。下面给出最小配置、预检验证方式和常见失败点。
前置条件:先确认两端地址和请求类型
跨域出现的前提是前端和后端协议、域名或端口不一致。本地开发最常见的情况是 Vite 或 Create React App 跑在 http://localhost:5173,FastAPI 跑在 http://127.0.0.1:8000。浏览器控制台报“CORS policy: No Access-Control-Allow-Origin”,网络面板里能看到失败的 fetch/XHR 请求。
操作前先确认 FastAPI 接口在本机可访问:访问 http://127.0.0.1:8000/docs 能看到 Swagger 文档。前端调用地址和这里的 origin 要区分开。
在 FastAPI 里添加 CORSMiddleware
在 FastAPI 主应用文件里添加中间件,把前端地址写进 allow_origins,并允许需要的 HTTP 方法和请求头。这一步通常能覆盖绝大多数简单跨域和预检场景。
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=['http://localhost:5173'],
allow_credentials=True,
allow_methods=['*'],
allow_headers=['*'],
)如果前端通过 127.0.0.1 访问,就把 allow_origins 改成 ['http://127.0.0.1:5173'];多个来源用列表。本地调试一般不推荐用 ['*'],因为一旦 allow_credentials 为 True,部分浏览器会直接拒绝通配符来源。
用 curl 验证预检请求
保存代码后重启 uvicorn。预检请求不是 GET/POST,而是 OPTIONS,浏览器只在跨域请求是“非简单请求”时才会先发预检。模型 API 一般会携带 JSON 头部或自定义 Header,肯定会触发预检。
在另一个终端执行以下命令,把 URL 换成实际模型接口路径:
curl -i -X OPTIONS 'http://127.0.0.1:8000/your-model-endpoint' -H 'Origin: http://localhost:5173' -H 'Access-Control-Request-Method: POST'预期响应状态码是 200 或 204,且响应头里包含 Access-Control-Allow-Origin: http://localhost:5173。如果响应头里有这个值,说明预检已通过。前端重新发起请求,CORS 错误通常会消失。也可以直接在浏览器 Network 面板里选中那条 OPTIONS 请求看响应头。
失败时回退:检查这三个方向
1. 核验 allow_origins 是否和前端地址完全一致,包括协议、host 和端口。常见错误是少了端口,或者把 localhost 和 127.0.0.1 混用。
2. 检查中间件是否挂载在你实际接收请求的 app 上。如果项目使用 create_app 工厂模式或挂载了子应用,需要确认 add_middleware 添加到了最外层应用。
3. 如果 OPTIONS 返回 405 或 404,先确认请求路径是否正确,再确认中间件代码没有因为模块导入顺序而未生效。也可临时去掉 allow_credentials,改用 allow_origins=['*'] 测试,但仅限本地开发。
跨域问题在配置成功后,网络面板会看到预检请求和实际请求都正常返回。如果仍然报错,建议在前端代码里打印响应头,确认服务端是否真的返回了 Access-Control-Allow-Origin。