FastAPI 实战：跨域问题（CORS）完整解决方案

PeterMap
2 阅读8分钟

在前后端分离开发中，跨域问题是最常见的拦路虎之一。前端项目（如Vue、React）通常运行在本地开发服务器（如localhost:3000），而后端FastAPI服务运行在另一个端口（如localhost:8000），此时浏览器会因安全机制拦截前端请求，导致接口调用失败。本文将详细讲解跨域的核心概念、同源规则，以及FastAPI中如何通过CORS中间件快速解决跨域问题，结合可直接运行的代码示例，覆盖开发环境、生产环境等不同场景，确保解决方案实用、可落地，全程围绕跨域问题核心展开。

一、什么是跨域问题？

跨域问题的本质是浏览器的同源安全策略，该策略是浏览器为了保护用户数据安全而设置的核心机制，它限制了一个源的Web应用只能访问同源的资源，禁止向不同源的服务器发起请求，除非服务器明确授权。

1. 同源的三个核心条件

判断两个资源是否同源，需同时满足以下三个条件，缺一不可：

  1. 协议相同：如均为http或均为https，http与https属于不同协议，会触发跨域；

  2. 域名相同：如www.example.com与blog.example.com属于不同域名，会触发跨域；

  3. 端口相同：如localhost:3000与localhost:8000，端口不同，会触发跨域。

只要有一个条件不满足，就属于跨域请求，浏览器会拦截该请求，导致接口调用失败，常见报错如“Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy”。

2. CORS的作用

跨域资源共享（CORS）是对同源安全策略的补充，它允许后端服务器主动告诉浏览器：“指定的前端源可以访问我的资源”。通过在后端配置CORS，可实现跨域请求的正常通信，既保留了浏览器的安全机制，又满足了前后端分离开发的需求。

二、FastAPI解决跨域的核心方案：CORS中间件

FastAPI内置了专门的CORS中间件（fastapi.middleware.cors.CORSMiddleware），无需额外安装依赖，只需简单配置，即可快速解决跨域问题。核心思路是通过配置中间件，让后端服务器返回允许跨域的响应头，告知浏览器授权的前端源、请求方法和请求头。

1. 基础配置（开发环境专用）

开发阶段，为了提高开发效率，通常允许所有前端源、所有请求方法和请求头访问后端，此时可配置最简版CORS中间件，快速解决跨域问题。

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

# 初始化FastAPI应用
app = FastAPI(title="跨域解决方案演示", version="1.0.0")

# 配置CORS中间件（开发环境）
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 允许所有前端源访问，开发环境推荐
    allow_credentials=True,  # 允许前端携带Cookie（如用户登录状态）
    allow_methods=["*"],  # 允许所有请求方法（GET、POST、PUT、DELETE等）
    allow_headers=["*"],  # 允许所有请求头（如Content-Type、Authorization等）
)

# 测试接口（用于验证跨域配置是否生效）
@app.get("/api/test")
async def test_cors():
    return {
        "code": 200,
        "message": "跨域配置生效，请求成功",
        "data": {"content": "FastAPI跨域测试成功"}
    }

# 启动项目：uvicorn main:app --reload

说明：allow_origins=["*"]表示允许所有前端源访问，适合开发阶段使用；allow_credentials=True用于支持前端携带Cookie，若项目不需要用户登录等状态保持，可设为False。

2. 规范配置（生产环境专用）

生产环境中，为了保证服务安全，不能允许所有前端源访问，需指定具体的授权前端域名，限制请求方法和请求头，避免非法请求。

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

# 初始化FastAPI应用
app = FastAPI(title="生产环境跨域配置", version="1.0.0")

# 配置授权的前端源（生产环境需明确指定，多个域名用列表表示）
authorized_origins = [
    "https://your-frontend-domain.com",  # 正式前端域名
    "http://test.your-frontend-domain.com",  # 测试前端域名
    "http://localhost:3000"  # 预留本地开发域名，上线前可删除
]

# 配置CORS中间件（生产环境规范配置）
app.add_middleware(
    CORSMiddleware,
    allow_origins=authorized_origins,  # 仅允许指定的前端源访问
    allow_credentials=True,  # 允许携带Cookie
    allow_methods=["GET", "POST", "PUT", "DELETE"],  # 仅允许常用请求方法
    allow_headers=["Content-Type", "Authorization"],  # 仅允许必要的请求头
    expose_headers=["X-Total-Count"]  # 可选：暴露自定义响应头给前端
)

# 业务接口示例
@app.post("/api/user/login")
async def user_login(username: str, password: str):
    # 模拟登录逻辑
    if username == "admin" and password == "123456":
        return {"code": 200, "message": "登录成功", "data": {"token": "fastapi_cors_demo"}}
    return {"code": 401, "message": "用户名或密码错误", "data": None}

说明：生产环境配置需遵循“最小授权”原则，仅开放必要的前端源、请求方法和请求头；expose_headers用于将后端自定义的响应头（如分页总数X-Total-Count）暴露给前端，供前端使用。

3. 模块化路由场景下的CORS配置

在模块化路由（按业务拆分路由）的项目中，CORS中间件只需在主入口文件（main.py）中配置一次，即可作用于所有挂载的路由，无需在每个路由文件中重复配置，简化配置流程。

# main.py（主入口文件）
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
# 导入模块化路由
from routers.user_router import user_router
from routers.order_router import order_router

# 初始化FastAPI应用
app = FastAPI(title="模块化路由跨域配置", version="1.0.0")

# 配置CORS中间件（全局生效，作用于所有路由）
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-frontend-domain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Content-Type", "Authorization"]
)

# 挂载模块化路由
app.include_router(user_router, prefix="/api/user", tags=["用户管理"])
app.include_router(order_router, prefix="/api/order", tags=["订单管理"])

# 基础测试接口
@app.get("/")
async def root():
    return {"message": "模块化路由跨域配置完成"}

# routers/user_router.py（用户模块路由，无需重复配置CORS）
from fastapi import APIRouter

user_router = APIRouter()

@user_router.get("/info")
async def get_user_info():
    return {"code": 200, "data": {"username": "admin", "role": "superadmin"}}

说明：CORS中间件是全局配置，挂载到主应用后，所有通过app.include_router()挂载的路由都会自动应用该跨域配置，无需在路由文件中额外编写跨域相关代码。

三、常见跨域问题排查与解决

配置CORS后，若仍出现跨域报错，可从以下几个常见场景排查，快速定位问题并解决：

1. 允许的源配置错误

报错特征：浏览器提示“Origin 'xxx' is not allowed by Access-Control-Allow-Origin”。

解决方法：检查allow_origins配置的域名是否正确，确保前端实际运行的域名在授权列表中；注意域名末尾不要加“/”（如正确配置为your-frontend-domain.com，而非https://your-front…

2. 携带Cookie时跨域失败

报错特征：前端携带Cookie请求时，跨域报错，无Cookie时请求正常。

解决方法：确保CORS配置中allow_credentials=True，同时前端请求时需设置withCredentials: true（如Axios请求中配置withCredentials: true）；注意allow_origins不能为“*”，需指定具体域名（生产环境推荐）。

3. 自定义请求头被拦截

报错特征：前端携带自定义请求头（如Authorization、X-Request-Id）时，跨域报错。

解决方法：将自定义请求头添加到allow_headers配置中，确保后端允许该请求头访问。

四、CORS配置核心参数说明

FastAPI的CORSMiddleware提供了多个核心参数，根据项目需求灵活配置，以下是常用参数的详细说明：

  1. allow_origins：授权的前端源列表，必填项；开发环境可设为["*"]，生产环境需指定具体域名；

  2. allow_credentials：是否允许前端携带Cookie，可选，默认False；需前后端配合配置（前端设置withCredentials: true）；

  3. allow_methods：允许的请求方法列表，可选，默认["GET"]；建议开发环境设为["*"]，生产环境限制为常用方法；

  4. allow_headers：允许的请求头列表，可选，默认[]；需包含前端传递的所有请求头（如Content-Type）；

  5. expose_headers：允许暴露给前端的响应头列表，可选，默认[]；用于前端获取后端自定义的响应头。

总结

跨域问题是前后端分离开发中不可避免的问题，而FastAPI的CORSMiddleware提供了简洁、高效的解决方案，无需复杂的配置，即可快速实现跨域请求的正常通信。本文通过基础配置、生产环境配置、模块化路由配置三种场景，结合独立构思的代码示例，覆盖了大部分开发场景的跨域需求，同时讲解了常见问题的排查方法和核心参数说明。

在实际开发中，需根据项目环境（开发/生产）灵活调整CORS配置，开发阶段优先保证开发效率，生产阶段优先保证服务安全，遵循“最小授权”原则，既解决跨域问题，又保障服务的安全性和稳定性。

avatar
文章
阅读
粉丝