FastAPI CORS（跨域资源共享）配置详解教程

1. 什么是CORS？

CORS（Cross-Origin Resource Sharing，跨域资源共享）是一种安全机制，允许Web应用程序从不同源（域、协议或端口）的服务器请求资源。由于浏览器的同源策略限制，默认情况下，脚本只能访问相同源的资源，而CORS通过添加特定的HTTP头来放宽这些限制。

• 为什么需要CORS？ 例如，当你开发的前端应用运行在http://localhost:3000，而API后端运行在http://localhost:8000时，前端调用API会遇到跨域错误，CORS配置可以解决这个问题。
• 同源策略：浏览器安全策略，限制跨域请求，以保护用户数据。

2. 在FastAPI中配置CORS

FastAPI使用中间件（Middleware）来处理CORS，主要通过fastapi.middleware.cors模块实现。我们需要安装和导入相关模块来启用CORS支持。

2.1 安装FastAPI和CORS支持

首先，确保你已经安装了FastAPI和uvicorn（用于运行服务器）。可以通过pip安装：

pip install fastapi uvicorn

安装CORS中间件（它包含在FastAPI中，但需要显式导入）：

• 无需额外安装，因为fastapi.middleware.cors是FastAPI的一部分。

2.2 导入和配置CORS中间件

在FastAPI应用中，你需要导入CORSMiddleware并添加到应用中。以下是一个完整的示例代码。

代码示例：基本CORS配置

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

# 创建FastAPI应用实例
app = FastAPI()

# 配置CORS中间件
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "https://yourfrontend.com"],  # 允许的源列表，可以指定具体域名或使用"*"（不推荐生产环境）
    allow_credentials=True,  # 允许发送凭据（如cookies）
    allow_methods=["GET", "POST", "PUT", "DELETE"],  # 允许的HTTP方法
    allow_headers=["*"],  # 允许的请求头，可以使用列表或"*"表示所有
)

# 定义示例路由
@app.get("/")
async def read_root():
    return {"message": "Hello, CORS enabled!"}

# 运行应用
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

2.3 配置选项详解

CORS中间件提供了多个参数来定制跨域行为：

• allow_origins：允许的源列表。可以是字符串列表，如["http://example.com", "https://another.com"]。使用"*"允许所有源，但出于安全考虑，建议在生产环境中指定具体域名。
• allow_credentials：布尔值，指示是否允许发送凭据（如cookies、Authorization头）。如果设置为True，则allow_origins不能为"*"，必须指定具体域名。
• allow_methods：允许的HTTP方法列表。默认是["GET"]，但通常设置为["*""]或特定方法如["GET", "POST", "PUT", "DELETE"]。
• allow_headers：允许的请求头列表。可以是["*""]允许所有头，或指定如["Content-Type", "Authorization"]。
• expose_headers：允许前端访问的响应头列表。默认为空，可以添加如["X-Custom-Header"]。
• max_age：预检请求（preflight request）的缓存时间，以秒为单位。例如，设置max_age=600缓存10分钟。

2.4 预检请求（Preflight Request）

对于复杂请求（如使用特定方法或头），浏览器会先发送一个OPTIONS请求来检查CORS策略。CORS中间件自动处理这些请求，无需额外代码。

示例：处理预检请求

如果前端发送POST请求带自定义头，浏览器会自动发送OPTIONS请求。CORS配置如上即可处理。

3. 常见配置场景

场景1：允许所有源（仅用于开发环境）

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 允许所有源
    allow_credentials=False,  # 由于允许所有源，不能设置True
    allow_methods=["*"],
    allow_headers=["*"],
)

场景2：指定多个域名并允许凭据

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "https://myapp.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Content-Type", "Authorization"],
)

场景3：动态允许源（基于环境变量）

import os

allowed_origins = os.getenv("ALLOWED_ORIGINS", "http://localhost:3000").split(",")
app.add_middleware(
    CORSMiddleware,
    allow_origins=allowed_origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

4. 测试CORS配置

部署应用后，可以使用工具如浏览器开发者工具或curl测试。

• 使用curl模拟跨域请求：

  curl -X GET http://localhost:8000/ -H "Origin: http://localhost:3000"
  

  检查响应头中是否有Access-Control-Allow-Origin。

• 前端调用：在JavaScript中使用fetch或axios调用API，观察是否出现CORS错误。

5. 安全注意事项

• 在生产环境中，避免使用allow_origins=["*"]，因为这可能会允许恶意网站访问你的API。
• 如果使用allow_credentials=True，确保allow_origins指定具体域名，以防止跨站请求伪造（CSRF）攻击。
• 定期审查和更新允许的源列表，以适应应用的变化。

6. 总结

CORS配置是FastAPI中处理跨域请求的关键部分。通过添加CORSMiddleware并适当设置参数，你可以轻松允许前端从不同源访问API。本教程从基础概念到实际代码，覆盖了常见配置场景，帮助新手快速上手。

如果你遇到问题，可以查阅FastAPI官方文档或社区资源。不断实践和调整配置，以匹配你的应用需求。