access-control 头部

June 17, 2023March 17, 2025

请求

在发出非简单请求之前，会先发送 Preflight 请求（请求方法为 OPTIONS）

流式请求永远是跨源请求，即必须预检

对于 CORS-safelisted request header，客户端无需指明 Access-Control-Request-Headers。
对于 CORS-safelisted response header，服务端无需指明 Access-Control-Allow-Headers。

显然：只有 OPTION 请求才会携带 Access-Control-Request-* 请求头。

Access-Control-Request-Headers

指明将要使用的请求头。多个时，使用逗号分隔。

注意：Forbidden header name 请求头禁止通过编程修改。因此这些请求不可能出现在 Access-Control-Request-Headers 中。

Access-Control-Request-Method

指明将要使用的请求方法。只指定一个。

响应

Access-Control-Allow-Origin

此标头必须对预检请求和实际请求都返回

只能指定一个。若为不带 Credentials 请求，也可使用通配符。

注意：浏览器的 Origin 请求头，仅当跨源请求会发送，仅当 URL 协议为 chrome-extension, chrome-untrusted, data, edge, http, https, isolated-app 时会正确携带，否则被设置为 Origin: null（例如浏览器直接打开文件，则为 file 协议）

Access-Control-Allow-Credentials

此标头必须对预检请求和实际请求都返回

指定当客户端发送跨源的 Credentials 时，是否允许客户端获取服务端的响应内容。
（也可以说，是否允许客户端发送跨源 Credentials，不允许就不能获取服务端响应内容）

注意：Request.credential = "include" 的请求，就是发送跨源 Credentials 的请求。
此时请求头会自动携带 Cookie 或 HTTP 认证头。（此时不会携带 Access-Control-Request-Headers: Cookie, Authorization）

在浏览器中手动构造请求时，手动构造的 Cookie 请求头永远会被忽略，就像没有被设置过一样（因为它属于禁止修改的请求头）。
手动构造请求携带的 HTTP 认证请求头，不属于跨源 Credentials。（会携带 Access-Control-Request-Headers: Authorization 预检请求头）

Access-Control-Allow-Headers

此标头仅对预检请求有效

指明允许客户端发送的非 CORS 白名单请求头。多个时，可用逗号分隔。
若预检请求携带了 Access-Control-Request-Headers 请求头，则必须响应 Access-Control-Allow-Headers，否则跨源失败。
若客户端的请求是无 Credentials 请求，则可以响应通配符 *，允许所有请求头。

Access-Control-Allow-Methods

此标头仅对预检请求有效

与上同理。

有一种特殊情况是客户端手动构造 OPTIONS 请求，此时会发送两个 OPTIONS 请求。
不过实际情况下几乎不可能有人会手动构造 OPTIONS 请求。

Access-Control-Expose-Headers

此标头仅对实际请求有效

指明向客户端暴露的响应头。多个时，使用逗号分隔。若为不带 Credentials 请求，也可使用通配符。
对于非暴露的且非 CORS 白名单的响应头，客户端将获取到 null 值。

注意：此响应头必须对实际请求返回，而非 OPTIONS 请求。

Access-Control-Max-Age

此标头仅对预检请求有效

指定 preflight 请求可缓存的秒数。若指定为 -1，则禁用缓存。
目前，Chromium 中默认值为 5，最大可为 7200

示例

一个最宽容的 CORS 配置（不要在生产环境下使用）

const express = require("express");
const app = express();

app.use("/*", (req, res, next) => {
    if (req.headers.origin) {
        res.header("access-control-allow-origin", req.headers.origin !== "null" ? req.headers.origin : "*");
        res.header("access-control-allow-credentials", "true");
    }
    next();
});

app.options("/*", (req, res) => {
    res.header("access-control-allow-headers", req.headers["access-control-request-headers"]);
    res.header("access-control-allow-methods", req.headers["access-control-request-method"]);

    res.header("access-control-max-age", "7200");

    // 无意义！
    // res.header("access-control-expose-headers", "x-test-expose");

    res.send();
});

app.get("/*", (req, res) => {
    const customHeaders = new Headers({ "x-test-expose": "foo" });
    res.setHeaders(customHeaders);
    res.header("access-control-expose-headers", [...customHeaders.keys()].join(", "));

    // 无意义！
    // res.header("access-control-allow-headers", "Authorization");
    // res.header("access-control-allow-methods", "GET,POST,PUT,PATCH,DELETE");
    // res.header("access-control-max-age", "7200");

    res.send();
});

app.listen(3000);

或者直接使用 http 模块

const http = require("http");
http.createServer((req, res) => {
    enableCORS(req, res);
    // Your logic here...
    res.end();
}).listen(3000);

function enableCORS(req, res) {
    if (!req.headers.origin) return;
    res.setHeader("access-control-allow-origin", req.headers.origin !== "null" ? req.headers.origin : "*");
    res.setHeader("access-control-allow-credentials", "true");

    if (req.method === "OPTIONS") {
        res.setHeader("access-control-allow-headers", req.headers["access-control-request-headers"] || "*");
        res.setHeader("access-control-allow-methods", req.headers["access-control-request-method"] || "*");
        res.setHeader("access-control-max-age", "7200");
    } else {
        res.setHeader("access-control-expose-headers", "*");
    }
}

←Back to home

This work is licensed under CC BY-NC-SA 4.0