CORS 与预检
本合集目录
本章目录
单册说明:本文件是卷 5 的第 7 章,可独立阅读。前置:5.6(统一错误体已就位)。本章先让你亲手撞一次 CORS 报错,再把它修好,并说清"为什么生产环境可能根本不需要它"。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 5 · 后端与 API(第 7 / 8 章) |
| 前置章节 | 5.6 错误处理与日志 |
| 本章产出 | 一段可复现的 CORS 报错 + 一份最小可用的 CORSMiddleware 配置 |
| 对应代码 | backend/app/main.py(加中间件)、cors-demo/index.html(实验页) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能说出"为什么请求成功了但我拿不到数据",并能判断该配 CORS 还是该用代理 |
5.7.1 一句话结论:CORS 是浏览器替服务器把关,服务器不表态浏览器就不给
先看你在控制台会看到的东西(Chrome,形如):
Access to fetch at 'http://127.0.0.1:8000/api/notes' from origin 'http://127.0.0.1:5500'
has been blocked by CORS policy: Response to preflight request doesn't pass access
control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
这段文字有 90% 的人读错,读成"请求被拦截了"。请求没被拦。
打开后端日志你会发现:那条请求已经到达、已经执行、POST 甚至已经把数据写进去了。浏览器只是在"把响应交给 JS"这一步把门关上了。
所以本章最重要的一句话是:
CORS 不保护你的服务器,它保护的是"用户在别的网站上时,那个网站读不到你的数据"。
理解这一点,你就不会再问"为什么 Postman 能通、浏览器不行"——Postman 不是浏览器,没有同源策略。
5.7.2 原理与方法
同源:三个东西全一样才算
| 页面地址 | 请求地址 | 同源? | 差异在哪 |
|---|---|---|---|
http://localhost:3000 |
http://localhost:3000/api |
是 | — |
http://localhost:3000 |
http://localhost:8000/api |
否 | 端口不同 |
http://localhost:3000 |
http://127.0.0.1:3000/api |
否 | 域名不同(localhost 与 127.0.0.1 是两个主机名) |
https://dudao.example.com |
http://dudao.example.com/api |
否 | 协议不同 |
https://dudao.example.com |
https://api.dudao.example.com/x |
否 | 子域名不同 |
协议 + 域名 + 端口,三者全等才是同源。 最后一行最容易被忽略:同一个主域下的不同子域,也算跨源。
反向也要记住:同源策略不是"禁止发请求",它禁止的是:
| 行为 | 同源策略管不管 |
|---|---|
| 把请求发出去(含 POST 的副作用) | 不管,照发 |
| 读响应体 | 管,跨源时读不到 |
| 读响应头 | 管,默认只暴露少数几个 |
| 设置某些请求头 | 管,跨源时不能随便加 |
| 带 Cookie | 管,默认不带 |
这就解释了一个让人抓狂的现象:数据被改了,但页面报错。因为写入发生在服务端,读取被拦在浏览器。
简单请求与预检:两种待遇
浏览器把跨源请求分两类:
| 条件(全满足才是"简单请求") | 具体值 |
|---|---|
| 方法 | 只有 GET、HEAD、POST |
| 请求头 | 只能用安全列表里的(Accept、Accept-Language、Content-Language、Content-Type 等) |
Content-Type |
只能是 text/plain、multipart/form-data、application/x-www-form-urlencoded |
发 JSON 的请求一定不是简单请求——application/json 不在那三个值里。所以你要调一个 JSON API,几乎必然触发预检。
两种待遇的差别:
| 简单请求 | 需要预检的请求 | |
|---|---|---|
| 请求次数 | 1 次 | 2 次(先 OPTIONS,通过了再发真的) |
| 第一个请求的方法 | 真实方法 | OPTIONS |
| 谁决定放行 | 响应里的 Access-Control-Allow-Origin |
预检响应里的 ACAO + ACAM + ACAH |
| 失败时 | 真实请求已执行,响应被拦 | 真实请求根本没发 |
最后一行是排错的关键:预检失败时,你的业务代码一次都没跑,日志里也不会出现那条 POST。 所以"日志里没有这条请求"不等于"前端没发",要去看 OPTIONS。
预检的完整往返:
浏览器 后端
│ OPTIONS /api/notes │
│ Origin: http://127.0.0.1:5500 │
│ Access-Control-Request-Method: POST │
│ Access-Control-Request-Headers: content-type
│ ──────────────────────────────────────►│
│ │ 判断 origin/method/headers 是否允许
│ ◄──────────────────────────────────────│
│ 200 + Access-Control-Allow-Origin │
│ + Access-Control-Allow-Methods │
│ + Access-Control-Allow-Headers │
│ + Access-Control-Max-Age: 600 │
│ │
│ POST /api/notes(真实请求) │
│ ──────────────────────────────────────►│
Max-Age 是"这次放行的有效期",浏览器在 600 秒内不再重复预检同一个组合。这也解释了一个常见困惑:改完后端配置,刷新页面还是报错——可能是浏览器还在用缓存的预检结果,需要强刷或换个端口。
实测:一次合格的预检响应长什么样
用 5.7.3 的配置启动后,手工发一次预检:
curl -i -X OPTIONS http://127.0.0.1:8000/api/notes \
-H "Origin: http://127.0.0.1:5500" \
-H "Access-Control-Request-Method: POST" \
-H "Access-Control-Request-Headers: content-type"
实测响应(节选):
HTTP/1.1 200 OK
vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers, ...
access-control-allow-origin: http://127.0.0.1:5500
access-control-allow-methods: GET, POST, PATCH, DELETE, OPTIONS
access-control-allow-headers: Accept, Accept-Language, Content-Language, Content-Type
access-control-allow-credentials: true
access-control-max-age: 600
逐行读:
| 头 | 作用 | 写错的后果 |
|---|---|---|
Access-Control-Allow-Origin |
我允许这个源 | 少了 → 浏览器拦;写错源 → 拦 |
Access-Control-Allow-Methods |
允许这些方法 | 少了 PATCH → 改不了 |
Access-Control-Allow-Headers |
允许这些请求头 | 少了 Content-Type → JSON 发不出去 |
Access-Control-Allow-Credentials |
允许带 Cookie | 少了 → 登录态丢(卷 6) |
Access-Control-Max-Age |
预检缓存多久 | 太短 → 每次都多一次往返 |
Vary: Origin |
告诉缓存"这个响应因源而异" | 少了 → CDN 把 A 站的响应发给 B 站 |
Vary 那行是专业细节:没有它,中间缓存可能把"允许 A 站"的响应复用给 B 站,等于把所有源都放行了。
被拒绝时,服务端返回什么
同一个请求换个源:
curl -i -X OPTIONS http://127.0.0.1:8000/api/notes -H "Origin: http://evil.test" \
-H "Access-Control-Request-Method: POST"
实测:
HTTP/1.1 400 Bad Request
Disallowed CORS origin
注意:服务端返回了 400,但浏览器控制台里你看不到这个 400,只看到"CORS policy"的报错。因为响应里没有 Access-Control-Allow-Origin,浏览器连状态码都不让你读。
这是本章最容易误判的一点:服务端日志里有 400,前端只看到 CORS 错误。 遇到"前端说 CORS,后端说 400",先对一下 Origin 是否在名单里。
凭据:为什么 * 和 Cookie 不能同时用
| 配置 | 浏览器行为 |
|---|---|
ACAO: *,不带凭据 |
允许 |
ACAO: *,请求带凭据(credentials: 'include') |
拒绝,规范明确禁止 |
ACAO: http://具体源,带凭据 |
允许,且响应必须是 ACAO 具体值 + ACAC: true |
我实测了 FastAPI 的一处实现细节,值得知道。配置成:
allow_origins=["*"], allow_credentials=True
这时服务端不会返回 *,而是把请求的 Origin 原样回显:
access-control-allow-origin: http://localhost:3000
access-control-allow-credentials: true
结果是"能通"。但这不是好消息:它意味着任何网站带用户 Cookie 调你的接口都能读到数据。这是最典型的"看起来修好了,其实把门全开了"。正确做法是显式列出允许的源。
withCredentials 的坑:三件事必须同时成立
前端要带 Cookie,条件是一个都不能少:
| # | 位置 | 要写成 |
|---|---|---|
| 1 | 前端 | fetch(url, { credentials: 'include' })(默认是 same-origin,跨源不带) |
| 2 | 后端 | allow_credentials=True,且 allow_origins 是具体源、不能用 * |
| 3 | Cookie 本身 | SameSite 允许跨站(卷 6 讲),Secure 要求 HTTPS |
少任何一个,表现都不同:
| 少了哪个 | 症状 |
|---|---|
前端 credentials |
请求能通,但后端看到的是"未登录"(401) |
后端 allow_credentials |
浏览器报 CORS 错,而且不会告诉你是因为凭据 |
Cookie 的 SameSite |
请求发出去了,Cookie 没带上,同样是 401 |
三种解法,选一个
| 方案 | 做法 | 适合 | 代价 |
|---|---|---|---|
| 配 CORS | 后端白名单放行前端源 | 前后端不同域部署,且要跨域调用 | 要维护名单,容易配错 |
| 开发代理 | 让开发服务器转发 /api 到后端 |
本地开发 | 只解决开发,生产还要另想办法 |
| 同源部署 | 前端与 /api 在同一个域名下(Nginx 分流) |
生产首选 | 需要会配 Nginx(卷 7) |
第三种最省事:https://dudao.example.com/ 是前端,https://dudao.example.com/api/notes 是后端,同源,不需要任何 CORS 头。卷 7 会用 Nginx 的 location /api/ 把请求转给后端进程,浏览器全程以为自己在跟一个站说话。
开发代理的原理也是这个思路:
浏览器 ──同源──► 开发服务器 (localhost:3000)
│ /api/* 转发
▼
后端 (127.0.0.1:8000)
浏览器只看到 localhost:3000/api/notes,同源,不预检;转发是服务器之间的事,没有同源策略。Next.js 的写法(next.config.mjs):
const nextConfig = {
async rewrites() {
return [{ source: '/api/:path*', destination: 'http://127.0.0.1:8000/api/:path*' }];
},
};
export default nextConfig;
Vite(卷 3 的工程)的写法(vite.config.js):
export default defineConfig({
server: {
proxy: { '/api': 'http://127.0.0.1:8000' },
},
});
两者的取舍:
| 用代理 | 用 CORS |
|---|---|
前端代码里写相对路径 /api/notes,不需要 baseURL |
前端要写完整地址或配 baseURL |
| 生产可以照搬同源部署,不用改前端 | 生产要维护 allow_origins 名单 |
| 代理会多一跳,本地调试时后端日志里的来源 IP 是代理 | 直连,日志更真实 |
本书第 8 章用环境变量 + 直连(方便你看到 CORS 的真实行为),生产上线时走同源部署。两条路都走一遍,你才知道它们的区别在哪。
5.7.3 动手:先撞墙,再修墙
第一步:造一个"另一个源"的页面
新建 cors-demo/index.html:
<!doctype html>
<meta charset="utf-8">
<title>CORS 实验</title>
<button id="load">取列表</button>
<pre id="out"></pre>
<script>
const out = document.querySelector('#out');
document.querySelector('#load').addEventListener('click', async () => {
out.textContent = '请求中…';
try {
const res = await fetch('http://127.0.0.1:8000/api/notes', {
headers: { 'Content-Type': 'application/json' },
});
out.textContent = JSON.stringify(await res.json(), null, 2);
} catch (err) {
out.textContent = String(err);
}
});
</script>
为什么带 Content-Type: application/json?为了让它是"非简单请求",从而触发预检——这样你能同时看到预检和真实请求两条记录。
启动一个静态服务器(用标准库,不用装东西):
python -m http.server 5500 --directory cors-demo
打开 http://127.0.0.1:5500,点按钮。一定要用 127.0.0.1:5500 打开,不要双击文件——file:// 的源是 null,报错会变成另一种样子,反而不好对照。
第二步:看三处证据
| 看哪 | 你会看到 | 说明 |
|---|---|---|
| Console | blocked by CORS policy: Response to preflight request doesn't pass access control check |
预检没过 |
| Network | 一条 OPTIONS /api/notes,状态可能是 405 或 (failed) |
你的后端没有处理 OPTIONS 的路由 |
| 后端日志 | 只有那条 OPTIONS,没有 GET | 真实请求根本没发 |
第三条最能纠正误解:很多人以为"请求发了但被浏览器拦了"。在这个场景里,请求压根没发,因为预检就没通过。
顺便说:现在后端对 OPTIONS 的响应是 405 Method Not Allowed,因为 FastAPI 只注册了 GET/POST/PATCH/DELETE 四个方法。CORSMiddleware 会自己接管 OPTIONS 并返回 200,所以修好之后你会在日志里看到 OPTIONS ... status=200。
第三步:加上中间件
在 app/main.py 里,放在访问日志中间件之后(后加的在外层):
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["http://127.0.0.1:5500", "http://localhost:3000"],
allow_methods=["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
allow_headers=["Content-Type"],
allow_credentials=True,
max_age=600,
)
| 参数 | 为什么这么写 |
|---|---|
allow_origins 列具体源 |
不用 *,因为开了凭据;且端口必须写全 |
allow_methods 显式列出 |
默认只允许 GET,不加 PATCH 就改不了 |
allow_headers=["Content-Type"] |
预检里 Access-Control-Request-Headers 只报了你实际要用的头 |
allow_credentials=True |
为卷 6 的 Cookie 登录做准备;现在不开也不影响 |
max_age=600 |
10 分钟内不重复预检 |
重启后端,回浏览器点按钮。列表出来了——这次没有任何代码改动,只是后端多说了三句话。
第四步:用 curl 复核
curl -s -o /dev/null -D - http://127.0.0.1:8000/api/notes -H "Origin: http://127.0.0.1:5500" | grep -i access-control
实测:
access-control-allow-credentials: true
access-control-allow-origin: http://127.0.0.1:5500
真实请求的响应里也带 ACAO——每一份响应都要带,不只是预检。新手常犯的错是以为"预检过了就行",结果真实响应缺了头,浏览器照样拦。
5.7.4 三个坑
坑一:localhost 与 127.0.0.1 当成一个源
症状:allow_origins=["http://localhost:3000"],前端用 http://127.0.0.1:3000 打开,照样报 CORS。
成因:这是两个不同的主机名。浏览器按字符串比较 Origin,一模一样才算匹配,不做 DNS 解析上的等价判断。
修法:两个都写进名单(本章配置就是这么做的),或者在团队里约定"开发一律用 localhost,不许混用"。生产环境没有这个问题,因为域名唯一。
坑二:加了自定义请求头,预检突然失败
症状:之前能通,加了一个 X-Client-Time 头之后,控制台变成:
Request header field x-client-time is not allowed by Access-Control-Allow-Headers in preflight response.
成因:allow_headers 是白名单。你加了一个不在列表里的头,预检直接拒绝——而且真实请求不会发,所以后端日志里什么都没有。
修法:把这个头加进 allow_headers。更好的做法是别加自定义头:时间戳放 body 里、客户端信息放 User-Agent,都能避免多一次预检协商。每加一个自定义头,就多一个必须同步维护的配置项。
坑三:500 的响应上没有 CORS 头,前端只看到 CORS 错误
症状:接口明明 500 了,浏览器控制台却只显示 No 'Access-Control-Allow-Origin' header is present,你以为是跨域配置坏了,改了半天 allow_origins。
成因:中间件有顺序。CORSMiddleware 如果在内层,500 是由更外层的兜底逻辑生成的,响应没经过 CORS 中间件,自然没头。浏览器看不到头 → 报 CORS 错 → 把真正的 500 藏起来了。
修法:让 CORS 中间件在最外层(在 add_middleware 的调用顺序上靠后)。本章的写法就是先 @app.middleware("http") 定义访问日志、再 add_middleware(CORSMiddleware, ...),所以 CORS 在外层,500 也带头。诊断技巧:用 curl -H "Origin: ..." 直接看响应头,如果有 ACAO 而浏览器还说 CORS,那就是别的问题;如果没有,先修中间件顺序。
本章验收
- 亲手复现过一次预检失败的报错原文(不是看别人截图)
- 加上配置后,页面能取到列表,Network 里能看到
OPTIONS与GET两条 - 能用
curl分别验证预检响应与真实响应都带ACAO - 能解释"请求已经执行了,只是响应被浏览器扣下"
- 能说出生产环境为什么可以完全不用 CORS(同源部署)
自测
Q1:为什么 fetch 报 CORS 错,但后端日志里看不到这条请求?
看答案
因为它是"需要预检"的请求,而预检没通过。浏览器先发 OPTIONS,服务端没有返回允许的头,浏览器就判定"这个跨源请求不被允许",真实请求根本不发。所以日志里只有 OPTIONS(或者什么都没有,如果 OPTIONS 直接被路由拒绝)。要验证这一点,去看 Network 面板:只有一条 OPTIONS,没有对应的 POST/GET。反过来说,如果日志里能看到真实请求,说明预检过了,问题出在真实响应缺头。Q2:allow_origins=["*"] 加 allow_credentials=True,为什么"看起来能用"却更危险?
看答案
因为框架会退一步把请求的 Origin 原样回显(实测如此),于是浏览器认为匹配成功,请求通过。表面上"修好了",实际上任何网站都能带着用户的 Cookie 调用你的接口并读取结果——这正是 CORS 想防的事。规范本意是禁止 `*` 与凭据共存,框架为了让配置"能用"做了回显,但安全性完全取决于你有没有认真填名单。判断口诀:只要开了凭据,`allow_origins` 就必须是穷举的具体源。Q3:开发时用 Next 的 rewrites 代理,为什么就不需要配 CORS 了?生产环境怎么办?
看答案
因为浏览器只跟 `localhost:3000` 说话,请求路径是 `/api/notes`,同源,不触发预检。真正发给后端的那一跳是开发服务器发起的,服务器之间没有同源策略。生产环境有两条路:① Nginx 把 `/api/` 反代到后端进程,同样做到"浏览器眼里只有一个源",前端代码不用改;② 前后端分开部署(比如前端在 CDN、后端在另一台机器),那就必须配 CORS 白名单。本书选 ①,因为它同时省掉了 CORS 配置和一类排障成本。下一步
到这里,后端"能跑、能调、能联调"的三件基础设施都有了:契约、错误体、跨域。最后一章把前端的 data 层真正接到这个接口上,并给出一张"出问题先看哪"的分诊表。