Docker部署Fast-API时所有服务错误均显示为500 CORS错误

问题分析 #

在Docker容器内用uvicorn运行FastAPI时，所有错误均返回500状态码，浏览器提示Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.，但本地直接运行Python时错误显示正常，仅报错场景出现CORS问题。核心原因是FastAPI默认的异常处理响应（如内置500错误页）未经过你配置的CORSMiddleware，导致错误响应缺失CORS头，被浏览器拦截；同时容器环境下的错误处理逻辑与本地存在差异，掩盖了实际的401等错误码。

解决办法 #

1. 确保CORSMiddleware为第一个添加的中间件 #

中间件按添加顺序执行，将CORSMiddleware放在最前面，保证所有请求（包括异常请求）都先经过CORS处理：

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# CORS中间件必须放在所有中间件最顶部
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 后续添加其他中间件、路由逻辑

2. 自定义全局异常处理器，强制注入CORS头 #

覆盖FastAPI默认异常处理逻辑，确保所有错误响应都携带CORS头：

from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.middleware.cors import CORSMiddleware
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 处理所有HTTP标准异常
@app.exception_handler(StarletteHTTPException)
async def custom_http_exception_handler(request: Request, exc: StarletteHTTPException):
    response = JSONResponse(
        status_code=exc.status_code,
        content={"detail": exc.detail}
    )
    # 手动注入CORS头，确保跨域可访问
    response.headers["Access-Control-Allow-Origin"] = "*"
    response.headers["Access-Control-Allow-Credentials"] = "true"
    return response

# 处理所有未捕获的非标准异常
@app.exception_handler(Exception)
async def custom_exception_handler(request: Request, exc: Exception):
    response = JSONResponse(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        content={"detail": str(exc)}
    )
    response.headers["Access-Control-Allow-Origin"] = "*"
    response.headers["Access-Control-Allow-Credentials"] = "true"
    return response

3. 调整uvicorn启动参数，禁用默认错误页面 #

启动uvicorn时添加--no-server-header参数，强制使用FastAPI的错误处理逻辑，避免uvicorn返回自身的无CORS头错误页面：

uvicorn main:app --host 0.0.0.0 --port 8000 --no-server-header

验证方式 #

调用一个会抛出401的接口，检查浏览器控制台是否仍有CORS错误提示，同时查看响应头是否包含Access-Control-Allow-Origin，以及响应状态码是否正确显示为401。

内容的提问来源于stack exchange，提问作者Simon Warchol