如何在 FastAPI 中配置 CORS？

Question

Accepted Answer

**CORS**（跨源资源共享）是一种浏览器安全机制，用于控制来自一个**源**的网页是否可以调用您的 API（位于不同源上）。FastAPI 使用内置的 **`CORSMiddleware`** 来配置它。当不同域/端口上的前端调用您的 API 时，您会遇到 CORS。

## CORS 解决的问题

```text
A React app at http://localhost:3000 calling an API at http://localhost:8000 is
CROSS-ORIGIN (different port). The BROWSER blocks the response unless the API
sends CORS headers permitting that origin.
(origin = scheme + host + port)
```

## 配置 CORSMiddleware

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "http://localhost:3000"],  # ALLOWLIST of origins
    allow_credentials=True,         # allow cookies/auth (requires specific origins, not "*")
    allow_methods=["*"],             # or ["GET", "POST", ...]
    allow_headers=["*"],
)
```

中间件添加必要的 CORS 响应头，告诉浏览器允许哪些源、方法和头。浏览器强制执行这些规则。

## 安全性：限制源（不要使用 "*"）

```python
# ❌ allowing all origins — convenient but insecure for credentialed/private APIs
allow_origins=["*"]
# ✅ restrict to your known frontend origins (an allowlist)
allow_origins=["https://app.example.com"]
# NOTE: allow_credentials=True is INCOMPATIBLE with allow_origins=["*"]
```

在生产环境中，**将 `allow_origins` 限制在允许列表中**，而不是使用 `*`。此外，允许凭证（cookies/auth）需要特定的源——通配符不能与凭证一起使用。

## 一个关键误解

```text
CORS is enforced by the BROWSER, not the server. It does NOT protect your API from
non-browser clients (curl, Postman, other servers) — those ignore CORS entirely.
CORS only governs what browser JavaScript from other origins may do.
```

## 为什么这很重要

CORS 是 web 开发中最常见的障碍之一——几乎每个前端到 API 的设置都会遇到它（特别是在本地开发时使用不同的端口，以及在生产中使用单独的前端域），所以知道如何使用 FastAPI 的 `CORSMiddleware` 来配置它是实用的、频繁需要的知识。

了解*它为什么存在*（浏览器同源安全）、服务器如何通过响应头选择加入，以及如何配置它（允许的源、方法、头、凭证）是将前端连接到 FastAPI API 而不被请求阻止所必需的。

同样重要的是安全地配置它——将 `allow_origins` 限制在特定的允许列表中，而不是过于宽松的 `*`（并且理解凭证与通配符不兼容）——以及理解关键误解，即 **CORS 是浏览器机制，而不是 API 授权**（它不能防止非浏览器客户端）。

知道如何正确安全地设置 CORS 是任何由 web 前端使用的 FastAPI API 的日常重要知识。