本地Llama 3通过FastAPI构建Web界面时CORS跨域请求被拦截的解决办法

文章导读
在排查之前,我会先看一眼浏览器控制台的完整报错。如果浏览器控制台报错信息里包含“CORS policy”或“Access-Control-Allow-Origin”字样,且请求在Network面板中显示为(canceled)或直接变成红色,而FastAPI后端日志里却能看到该请求已经到达,那么基本可以确定是跨域拦截。这里有个容易忽略的点:CORS是浏览器行为,不是后端拒绝请求。你如果用curl、P
📋 目录
  1. Ⅰ 容易误判的两个点
  2. Ⅱ 建议的处理顺序:先配置CORSMiddleware
  3. Ⅲ 用预检请求验证配置是否生效
  4. Ⅳ 回滚和风险边界
A A

在排查之前,我会先看一眼浏览器控制台的完整报错。如果浏览器控制台报错信息里包含“CORS policy”或“Access-Control-Allow-Origin”字样,且请求在Network面板中显示为(canceled)或直接变成红色,而FastAPI后端日志里却能看到该请求已经到达,那么基本可以确定是跨域拦截。这里有个容易忽略的点:CORS是浏览器行为,不是后端拒绝请求。你如果用curl、Postman或直接用Python requests去访问后端接口,正常情况下都能拿到数据,因为根本不存在浏览器同源策略的限制。所以当用户反馈“前端调不通”时,先确认对方是不是在浏览器环境里调试,别急着改后端代码。

再看一眼FastAPI的uvicorn日志。如果同一个请求在后端有访问记录,返回的还是200,浏览器里却显示失败,方向就比较明确了。让前端把Network面板里Request Headers的Origin值发给你看,确认浏览器实际在往哪个源发请求。

容易误判的两个点

第一,后端日志有请求记录不代表CORS没问题。CORS拦截发生在浏览器收到响应之后,后端可能已经正常处理完请求了,所以日志里看到200并不能排除跨域因素。判断时要以前端控制台为准,不要只看后端。

第二,localhost和127.0.0.1在浏览器里被当作不同源。前端地址如果是http://127.0.0.1:3000,而后端配置里只写了http://localhost:3000,预检请求依然过不了。开发阶段把这两个值都放进allow_origins,能少踩一个坑。

本地Llama 3通过FastAPI构建Web界面时CORS跨域请求被拦截的解决办法

建议的处理顺序:先配置CORSMiddleware

在FastAPI中启用CORS最直接的方式是使用自带的CORSMiddleware。导入后实例化时注意三个关键参数:allow_origins、allow_methods、allow_headers。假设前端开发服务器跑在http://localhost:3000,后端是http://localhost:8000,就把allow_origins写成["http://localhost:3000","http://127.0.0.1:3000"],不要图省事用["*"]。因为如果后面设置了allow_credentials=True,通配符会失效并导致整个跨域配置不生效。通常建议allow_methods用["*"],allow_headers用["*"],但如果你需要携带自定义头,比如Authorization…

这些自定义头需要在allow_headers里显式加进去,否则预检阶段就会失败。下面这个配置可以先用起来:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "http://127.0.0.1:3000"],
    allow_methods=["*"],
    allow_headers=["*"]
)

这段代码要放在创建FastAPI实例之后、注册路由之前。如果你在FastAPI里封装的是Llama 3推理接口,前端多半用POST发送长段prompt,还可能带Authorization头或自定义的session_id,allow_headers先用["*"]开发,线上再收紧。

本地Llama 3通过FastAPI构建Web界面时CORS跨域请求被拦截的解决办法

用预检请求验证配置是否生效

配置写完后,别急着刷新页面。用下面的命令模拟浏览器发出OPTIONS预检请求:

curl -i -X OPTIONS http://localhost:8000/your-route \
  -H "Origin: http://localhost:3000" \
  -H "Access-Control-Request-Method: POST"

注意把端口、路径替换成实际的值。看返回的响应头里有没有Access-Control-Allow-Origin: http://localhost:3000,以及Access-Control-Allow-Methods、Access-Control-Allow-Headers是否包含预期值。如果预检返回403或者响应头里缺少CORS字段,优先检查中间件挂载顺序,确认CORSMiddleware加在路由定义之前;其次看有没有nginx或其他代理层提前拦截了OPTIONS,把响应头吞掉。

本地Llama 3通过FastAPI构建Web界面时CORS跨域请求被拦截的解决办法

curl预检通过后,再回到浏览器刷新页面验证。Network面板里原来的(canceled)请求恢复为正常状态,说明跨域已经通了。

回滚和风险边界

在本地开发时,允许所有来源(即allow_origins=["*"])或者设置allow_credentials=False倒也不是不行,但如果你把这个习惯带进生产环境,会有很大的安全隐患。因为CORS配置不当可能导致恶意网站直接向你的后端发请求,盗取用户信息。建议一个清晰的做法:在FastAPI配置里把allowed origins放到环境变量或配置文件中,根据环境区分。本地调试时用宽松配置,线上用精确域名列表。另外,即使配置了CORS,前端代码里仍然需要显式处理错误状态,不要只依赖浏览器报错,因为有些错误(比如网络中断)和CORS没关系,如果后端服务没启动,浏览器同样会显示“TypeError: Failed to fetch”,但没有CORS字样,这时候别再去改CORS了,先检查后端进程是否还在。

如果改了配置仍然不行,先把改动回退到上一版,用curl预检重新验证,确认响应头有变化后再继续调整。FastAPI的中间件代码改动后需要重启uvicorn进程再测,别漏掉这一步。后续维护时可以在后端日志里留意OPTIONS请求的出现:前端每次发非简单请求都会带一次预检,看到少量OPTIONS是正常现象,不用紧张。另外,如果prompt很长、模型推理耗时长,浏览器可能在预检通过后因为等待响应超时报错,这种报错不包含CORS字样,不属于跨域问题。