跳到正文
零到全栈 · 卷 5 · 后端与 API

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 层真正接到这个接口上,并给出一张"出问题先看哪"的分诊表。

→ 卷5-08-联调收口.md