页面可以向另一个源的服务器请求数据,但浏览器中的 JavaScript 不一定能够读取响应。跨源资源共享(CORS)是一种协议,服务器借助它告诉浏览器,哪些跨源响应可以暴露给发起请求的页面。把三个问题分开来看最容易理解:请求是否已发送?服务器是否执行了操作?发起调用的 JavaScript 能否读取响应?
下面的协议报文和代码是教学示例,使用保留的主机名 example.test,并不描述任何特定服务的技术栈。
1. 追踪请求之前先确定源
源由协议(scheme)、主机和端口三者组合而成。例如,https://app.example.test 和 https://api.example.test 属于不同的源,因为它们的主机不同,尽管二者有共同的父域名。同样,把 HTTPS 改为 HTTP,或者更改端口,都会改变源。仅仅改变路径或查询字符串则不会。
定义 7.1.1
(源与 CORS)
源(origin)是协议、主机和端口三者的组合。跨源资源共享(CORS)是服务器通过响应头声明哪些其他源可以读取其响应的协议。浏览器对网页内容执行这一决定,只有响应头允许时,才把响应暴露给发起调用的脚本。
同源策略限制页面访问跨源响应。CORS 提供了一种受控的例外:服务器可以返回适当的响应头,浏览器再把这些响应头与请求的源和凭据模式进行核对。CORS 由浏览器针对网页内容的访问来强制执行;它并不能阻止任意非浏览器客户端发送请求。服务器仍然必须独立地对操作进行身份验证和授权。
2. 浏览器何时发送预检?
发送跨源请求之前,浏览器会先对请求分类。同时满足以下条件的请求无需预检:方法是 GET、HEAD 或 POST;脚本设置的每个请求头都在 CORS 安全列表中(例如 Accept、Accept-Language、Content-Language、Content-Type 和简单的 Range,其值另有限制);并且 Content-Type 若存在,必须是 application/x-www-form-urlencoded、multipart/form-data 或 text/plain。另有少数条件涉及上传事件监听器和流式请求体。其他请求都属于非简单请求,包括 PUT、PATCH、DELETE 方法,任何自定义请求头或 Authorization 请求头,以及 Content-Type: application/json。
定义 7.1.2
(预检请求)
预检请求是浏览器在发送非简单的跨源请求之前,自行发出的 OPTIONS 请求。它不携带凭据,也不携带页面的请求体。Access-Control-Request-Method 指明打算使用的方法,Access-Control-Request-Headers 列出非安全列表请求头。只有响应的状态码表示成功,并且允许该源、该方法以及所列的每个请求头,浏览器才会发送实际请求。
服务器用 Access-Control-Allow-Origin、Access-Control-Allow-Methods 和 Access-Control-Allow-Headers 响应预检,还可以加上 Access-Control-Max-Age,让浏览器把许可缓存若干秒(上限由浏览器决定)。简单请求会跳过这一步,这会带来后面“两个不同阶段的失败”一节讨论的后果:即使响应之后不向脚本暴露,服务器仍可能已经执行了简单请求的操作。
常见错误
(对预检请求做身份验证)
服务器在处理 CORS 之前先做登录检查,使每个没有有效会话的请求都收到 401。浏览器发送预检时不携带网页的 Cookie,所以预检本身就收到 401。预检必须得到成功状态码,浏览器因此认为预检失败,不会发送实际请求,尽管那个带着 Cookie 的实际请求本来会被接受。应在认证步骤之前,先响应带有 Access-Control-Request-Method 的 OPTIONS 请求,再照常对实际请求进行认证。
3. 一次 JSON 提交及其预检
假设位于 https://app.example.test 的页面向 https://api.example.test/notes 发送一个 POST 请求。本例假设服务器实现了下面所示的约定,用户拥有一个符合条件的会话 Cookie,并且页面已经通过恰当的方式获得了一个应用专用的 CSRF 令牌。所示的令牌仅作说明之用。HTTPS、Cookie 是否符合条件以及浏览器策略都是该情境的一部分;代码中出现 credentials: "include" 并不能保证一定会携带 Cookie。
async function createNote(title, csrfToken) {
const response = await fetch("https://api.example.test/notes", {
method: "POST",
credentials: "include",
headers: {
"Content-Type": "application/json",
"X-CSRF-Token": csrfToken
},
body: JSON.stringify({ title })
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
return response.json();
}
这里的 application/json 不是 CORS 安全列表中的请求 Content-Type,X-CSRF-Token 也不是安全列表中的请求头。假设不存在适用的已缓存预检许可,浏览器会先发送一个 OPTIONS 预检请求。该请求会指明打算使用的方法和非安全列表请求头;它不携带实际的 JSON 请求体或令牌值。浏览器发送预检请求时不附带该请求的跨源凭据。以下 HTTP/1.1 风格的报文省略了无关的头部:
OPTIONS /notes HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, x-csrf-token
服务器以一个成功的响应允许这一组合,例如:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.test
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, X-CSRF-Token
Vary: Origin
允许的源与页面的源完全一致。允许的方法包括 POST,允许的头部包括所请求的两个名称;头部名称不区分大小写。这里需要 Access-Control-Allow-Credentials: true,因为随后的 Fetch 使用的凭据模式是 include。对于凭据模式为 include 的请求,通配符 Access-Control-Allow-Origin: * 无法授权访问其响应。当服务器根据请求的 Origin 来选择允许的源时,Vary: Origin 就很重要,它可以防止共享缓存不加区分地把为某个源生成的响应复用给另一个源。
预检成功只是允许浏览器发出实际请求;它本身并不是笔记的创建。在上述 Cookie 假设下,简化后的实际交互如下:
POST /notes HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
Cookie: sid=example-session
Content-Type: application/json
X-CSRF-Token: example-token
{"title":"Graph notes"}
HTTP/1.1 201 Created
Access-Control-Allow-Origin: https://app.example.test
Access-Control-Allow-Credentials: true
Content-Type: application/json
Vary: Origin
{"id":42,"title":"Graph notes"}
实际响应同样需要带有相应的 CORS 头部。在本例的约定下,201 和 JSON 响应体表示所创建的笔记;response.ok 为 true,response.json() 会解析响应体。如果响应体格式有误,解析仍可能失败。对于 CORS 头部允许暴露的非成功 HTTP 响应,Fetch 通常会以一个响应对象兑现(fulfill),而代码会在检查 response.ok 之后显式抛出错误。与此不同,浏览器的 CORS 失败在脚本看来表现为一次被拒绝的 Fetch;脚本代码无法检查被拦截响应的状态码或响应体。
4. 两个不同阶段的失败
如果预检未通过 CORS 检查,并且没有允许该请求的已缓存许可,浏览器就不会发送这个实际的 POST 请求。检查服务器对 OPTIONS 的响应以及浏览器的网络日志,有助于定位这类失败。反过来,假设预检成功,浏览器发送了 POST,服务器创建了笔记,而实际的 201 响应缺少 Access-Control-Allow-Origin。此时浏览器会阻止脚本读取该响应,尽管操作可能已经发生。因此,Fetch 被拒绝并不能证明写入没有发生。除非应用具有合适的服务器端幂等约定,否则盲目重试可能会创建第二条笔记。
旁注
用三个问题排查 CORS
依次发问:请求发出了吗?服务器执行操作了吗?脚本能读取响应吗?先在网络日志里找 OPTIONS 请求;它缺失或失败,就说明你正卡在哪一个问题上。
CORS 许可并不等于授权。服务器仍然必须检查会话,以及该用户是否有权创建笔记。CORS 也不能取代 CSRF 防护:对于基于 Cookie 认证的写操作,服务器必须采用适合其部署环境的防护措施,例如在合适的 Cookie 策略和源策略之外,再校验 CSRF 令牌。有些跨源请求无需预检即可发送,因此仅仅拒绝 CORS 对响应的访问,并不是阻止不期望的状态更改的通用方法。
反例模式
前缀比较不是来源允许列表
有人声称:只要检查 origin.startsWith("https://app.example.test") 就足以把该应用列入允许列表,然后服务器连同 Access-Control-Allow-Credentials: true 返回匹配的 Origin。考虑由 https://app.example.test.evil.test 提供的网页。它的来源字符串以允许的文本开头,检查通过,服务器于是响应 Access-Control-Allow-Origin: https://app.example.test.evil.test。若用户的浏览器会带上会话 Cookie,该网页的脚本便可读取 JSON 响应。更宽松的 origin.includes("example.test") 同样会放行 https://example.test.evil.test。正确做法是把整个来源与固定集合比较,正如下面第二个例题中的 allowedOrigins.has(origin):来源是协议、主机和端口作为整体,而不是字符串前缀。
5. 脚本可以读取哪些响应头
即使响应被允许,脚本默认也只能看到 CORS 安全列表中的响应头:Cache-Control、Content-Language、Content-Length、Content-Type、Expires、Last-Modified 和 Pragma。X-Total-Count 这类响应头会出现在浏览器的开发者工具中,但除非服务器同时发送 Access-Control-Expose-Headers: X-Total-Count,否则 response.headers.get("X-Total-Count") 会返回 null。这里同样说明:网络上看得见的内容,与脚本可以读取的内容并不相同。因此,以自定义响应头报告分页或频率限制信息的 API,必须明确列出这些响应头,否则浏览器脚本永远看不到它们。
常见错误
(用 no-cors 消除错误)
开发者遇到 CORS 错误,便在调用中加上 mode: "no-cors"。fetch 的确不再被拒绝,但响应是不透明的:状态码为 0、内容为空,也读不到任何响应头,所以脚本仍然什么也得不到。请求还被限制为简单的方法和头部。要修复错误,必须由服务器发送合适的 CORS 头部,而不是由调用方要求浏览器视而不见。
6. 例题详解
例题 7.1.3
(用通配符源读取公开的 GET)
位于 https://app.example.test 的页面在省略凭据的情况下运行以下代码。假设没有重定向,服务器返回带有 JSON 的 200 以及 Access-Control-Allow-Origin: *。
const response = await fetch("https://api.example.test/public-notes", { credentials: "omit" });
const notes = await response.json();
GET /public-notes HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
[{"id":1,"title":"Public note"}]
方法是 GET,脚本没有设置任何请求头,所以这是简单请求:浏览器直接发送,并自行加上 Origin 请求头。由于凭据模式是 omit,通配符是可以接受的,因此浏览器暴露该 200 响应,response.json() 解析出数组。这个请求无需预检,响应的 Content-Type: application/json 也不会触发预检,因为这一决定只取决于请求的请求头和方法。这并不会让数据变成机密;若服务器遗漏该响应头,同一个调用在浏览器中就会失败。
例题 7.1.4
(预检列出的方法不足的 PUT)
页面发送 fetch("https://api.example.test/notes/42", { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ title: "Renamed" }) })。服务器对浏览器预检的回答如下。
OPTIONS /notes/42 HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: content-type
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.test
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type
Vary: Origin
PUT 不在安全列表的方法之内,application/json 也不是安全列表的内容类型,所以必须预检。浏览器把请求的方法 PUT 与 Access-Control-Allow-Methods: GET, POST 匹配,发现没有列出,就认为预检失败。实际的 PUT 从未发送,所以笔记没有被改名;脚本的 fetch 以 TypeError 被拒绝,既读不到状态码,也读不到响应体。只有 OPTIONS 请求到达了服务器。修正要在服务器端进行:必须列出该方法和请求头。下面的中间件还会为来自被允许源的每个响应加上这些响应头,因为缺少这些响应头的错误响应同样会被拦截:
import express from "express";
const app = express();
const allowedOrigins = new Set(["https://app.example.test"]);
app.use((req, res, next) => {
const origin = req.get("Origin");
if (origin && allowedOrigins.has(origin)) {
res.set("Access-Control-Allow-Origin", origin);
res.set("Access-Control-Allow-Credentials", "true");
res.append("Vary", "Origin");
}
if (req.method === "OPTIONS" && req.get("Access-Control-Request-Method")) {
res.set("Access-Control-Allow-Methods", "GET, POST, PUT");
res.set("Access-Control-Allow-Headers", "Content-Type, X-CSRF-Token");
res.set("Access-Control-Max-Age", "600");
return res.status(204).end();
}
next();
});
app.use(express.json());
对不在集合内的源,中间件不会设置 Access-Control-Allow-Origin 响应头,因此浏览器会拦截该页面的访问。这些响应头只是通知浏览器;路由处理函数仍须对每个请求进行身份验证和授权。
例题 7.1.5
(写入成功,响应却被拦截)
“JSON 提交及其预检”一节的 POST 通过了预检,但应用的实际响应如下,没有任何 CORS 响应头。
HTTP/1.1 201 Created
Content-Type: application/json
{"id":43,"title":"Graph notes"}
浏览器已经发出请求,所以服务器执行了处理函数,并保存了 id 为 43 的笔记。响应到达时,浏览器找不到与页面的源匹配的 Access-Control-Allow-Origin,就不向脚本暴露该响应。脚本的 await fetch(...) 以 TypeError 被拒绝,代码无法查看这个 201。看到错误而点击重试的用户,可能会创建第二条笔记。要补救,服务器必须为实际响应(包括错误响应)加上 CORS 响应头。可安全重试的设计会保存由客户端生成的请求标识,或提供读取端点,让客户端能查明实际情况,而不是假定写入失败。
7. 练习
快速检查
(为三个请求分类)
就下列每个跨源请求,说明之前是否会有预检。(a) fetch(url, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: "a=1" })。(b) fetch(url, { method: "PUT" })。(c) fetch(url, { headers: { "X-Request-Id": "r1" } })。
解答
(a) 无需预检:只带表单内容类型的 POST 是简单请求。(b) 会发送预检,因为即使没有请求头或请求体,PUT 也不是 CORS 安全列表中的方法。(c) 会发送预检:方法虽是 GET,但 X-Request-Id 不在安全列表中。请求 (a) 即使之后 CORS 禁止脚本读取响应,仍可到达服务器并改变状态。
快速检查
(通配符与凭据)
页面调用 fetch(url, { credentials: "include" })。响应带有 Access-Control-Allow-Origin: * 和 Access-Control-Allow-Credentials: true。脚本能拿到响应吗?服务器应如何改为响应?
解答
不能。凭据模式为 include 时,通配符的 Access-Control-Allow-Origin 不能授权读取响应,Access-Control-Allow-Credentials: true 也无法补救。浏览器会拦截响应,fetch 被拒绝。服务器应把请求的 Origin 与允许列表比对,原样返回匹配的源,保留 Access-Control-Allow-Credentials: true,并加上 Vary: Origin,让缓存把不同源的响应区分开。
快速检查
(消失的响应头)
开发者工具显示被允许的跨源响应带有 X-Total-Count: 57,但 response.headers.get("X-Total-Count") 返回 null。请解释并修正。
解答
除非服务器暴露其他响应头,脚本只能读取 CORS 安全列表中的响应头,而 X-Total-Count 不在其中。服务器须在响应中加上 Access-Control-Expose-Headers: X-Total-Count,脚本才能读取该值。这个响应头并不是没有出现在网络流量中,只是对脚本隐藏。
快速检查
(把 CORS 当作安全墙)
开发者说:“我们的 API 只为 https://app.example.test 发送 CORS 响应头,所以其他网站或程序都无法调用它。”请指出两个错误。
解答
第一,CORS 是由浏览器对网页内容执行的。命令行客户端、另一台服务器上的脚本或被修改的浏览器都不理会它,可以发送任何请求。第二,即使在浏览器内,简单请求无需预检就会发送,CORS 只决定调用的脚本能否读取响应,并不决定服务器有没有处理请求。所以保护必须依靠服务器端的身份验证、授权和 CSRF 防护。
快速检查
(DELETE 与只列两种方法的预检)
DELETE /notes/42 的预检返回 204,带有正确的 Access-Control-Allow-Origin 和 Access-Control-Allow-Methods: GET, POST。哪些请求会到达服务器?脚本观察到什么?必须修改什么?
解答
只有 OPTIONS 预检到达服务器。浏览器发现没有列出 DELETE,认为预检失败,从不发送 DELETE,所以笔记仍然存在。脚本观察到被拒绝的 fetch,没有状态码或响应体。服务器必须把 DELETE 加入 Access-Control-Allow-Methods。这与第三个例题中被拦截的 201 不同,那次写入确实已经发生。