Access-Control-Allow-Headers

用法

当浏览器发出预检 OPTIONS 请求时，Access-Control-Request-Headers 头会列出客户端打算发送的非安全列表头。服务器以 Access-Control-Allow-Headers 作答，确认其中哪些头被接受。

CORS 安全列表头始终被允许，无需出现在此列表中。安全列表集合包括 Accept、Accept-Language、Content-Language、Content-Type（对媒体类型和值长度有限制）以及 Range（对格式有限制）。显式列出某个安全列表头会移除对其值的额外限制。

多个头名称以逗号分隔的列表形式出现。

头名称列表

一组以逗号分隔的头名称，表示服务器在实际请求中接受它们。

Access-Control-Allow-Headers: Content-Type, Authorization

*（通配符）

对于不带凭据的请求，星号充当通配符，允许任意头名称。

Access-Control-Allow-Headers: *

注意

对于带凭据的请求，通配符 * 会被当作字面字符串而非通配符处理。当存在凭据时，每个允许的头都必须显式列出。Authorization 头永远不会被通配符覆盖，必须始终显式指明。

示例

一个预检请求询问是否允许 Content-Type 和自定义的 X-Request-ID 头。服务器确认了两者。

请求

OPTIONS /api/data HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, X-Request-ID

响应

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, X-Request-ID
Access-Control-Max-Age: 86400

对于不带凭据的请求，服务器使用通配符以单个字符作答。

Access-Control-Allow-Headers: *

故障排查

与请求头相关的预检失败会产生控制台错误并阻止实际请求。

控制台显示”Request header field X is not allowed by Access-Control-Allow-Headers in preflight response.”。服务器未在 Access-Control-Allow-Headers 值中列出该头名称。请将缺失的头添加到预检响应中。在 nginx 中：add_header Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”; 在 Apache 中：Header set Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”

预检响应完全缺少该头。服务器处理了 OPTIONS 请求，但响应中未包含 Access-Control-Allow-Headers。许多框架要求为预检路由进行显式的 CORS 配置。请检查 OPTIONS 处理器或中间件是否在设置 Access-Control-Allow-Methods 和 Access-Control-Allow-Origin 的同时也设置了该头。

通配符 * 在带凭据的请求中不起作用。当 Access-Control-Allow-Credentials 为 true 时，通配符会被当作字面字符串 * 处理，无法匹配任何内容。请显式列出每个允许的头。Authorization 头即使在不带凭据的请求中也永远不会被通配符覆盖，必须始终显式指明。

在某些服务器上头名称看起来是区分大小写的。按照协议，HTTP 头名称不区分大小写，但某些服务器框架在检查允许列表时会执行区分大小写的字符串匹配。如果服务器只列出了 Content-Type，那么发送 content-type 的请求可能会失败。请匹配客户端发送的大小写，或在 CORS 配置中将两端都归一化为小写。

发送 Content-Type: application/json 触发了意外的预检。Content-Type 头仅在值为 application/x-www-form-urlencoded、multipart/form-data 和 text/plain 时才在安全列表内。值 application/json 不在安全列表范围内，会强制触发预检。请将 Content-Type 添加到 Access-Control-Allow-Headers 列表。要确认预检是否被触发，打开 DevTools 的 Network 标签并按方法筛选，以发现在实际请求之前出现的 OPTIONS 请求。