深入解析前端使用JavaScript(fetch或XMLHttpRequest)发送跨域请求时,因携带Cookie或自定义Header导致请求失败的核心原因、浏览器CORS预检机制、四重门槛检验与完整修复方案。
JS发送带Cookie或自定义Header的跨域请求为何失败
时间:2026-11-20
浏览:184
文章目录
在前端开发中,使用 JavaScript(fetch 或 XMLHttpRequest)向另一个源(协议、域名或端口不同)发送网络请求时,一旦在请求头中加入自定义字段(如 Authorization、X-Token)或开启 Cookie 传递,请求常常会在控制台直接抛出 CORS 错误。这一现象的核心根源在于:添加自定义 Header 会脱离浏览器的“简单请求”保护规范,强制触发 OPTIONS 预检请求,若服务端未正确放行该 Header 即会终止请求;而携带 Cookie 则触碰了浏览器的用户凭据安全红线,不仅前端必须主动声明开启凭据传输,服务端更被绝对禁止使用通配符(*)授权,且必须同时满足响应凭据许可与现代浏览器的第三方 Cookie 安全策略。
一、自定义 Header 为何失败:预检请求(Preflight)的拦截逻辑
在普通认知中,只要服务端配置了 Access-Control-Allow-Origin: *,跨域请求就能顺利通过。然而一旦在前端代码中添加了自定义请求头(例如用来传递身份凭据的 X-Token、Authorization,甚至是设置了 Content-Type: application/json),原本正常的请求就会立即失败。
这是因为 W3C 的跨域资源共享(CORS)规范将跨域请求严密划分为两类:简单请求(Simple Requests)与非简单请求(Preflighted Requests)。浏览器对这两类请求的处理策略存在本质差异。
1. 什么是简单请求的“安全列表”?
浏览器认定一个请求为“简单请求”,必须同时满足以下两个严苛条件:
- HTTP 方法限制:仅允许
GET、HEAD、POST三种方法之一。 - 请求头字段限制:只允许包含用户代理自动设置的头部(如 Connection、User-Agent 等),以及 CORS 安全列表指定的头部(CORS-safelisted request-header):
Accept、Accept-Language、Content-Language,以及限定值的Content-Type(仅限application/x-www-form-urlencoded、multipart/form-data、text/plain)。
一旦你在请求中附加了任何不在上述安全白名单中的自定义 Header(比如 X-Token: 123456 或 Authorization: Bearer xxx),或者将 Content-Type 设为现代 Web API 标配的 application/json,该请求就会被浏览器判定为非简单请求。
2. 预检请求(OPTIONS)如何导致失败
对于非简单请求,浏览器不会直接发出你的业务请求,而是出于安全防御机制,先在后台自动拦截并派出一次嗅探请求——即 HTTP OPTIONS 预检请求(Preflight Request)。
这次 OPTIONS 请求会向服务端明确询问:“我打算用这种方法,并携带以下 Header,你允许吗?”:
Origin:声明发起请求的客户端源(例如https://client.example.com)。Access-Control-Request-Method:声明后续真实请求的 HTTP 方法(例如POST)。Access-Control-Request-Headers:声明后续真实请求中携带的自定义请求头名称(例如authorization,content-type,x-token)。
此时,导致请求直接失败的常见阻断点集中在以下两处:
- 服务端未放行 OPTIONS 方法(返回 404 或 405):很多后端框架、网关或路由拦截器只定义了针对
GET和POST路由的处理逻辑,遇到未知或未经注册的OPTIONS请求时,直接返回了404 Not Found或405 Method Not Allowed。预检请求一旦没有得到成功的 HTTP 状态码(通常为 200 或 204),浏览器会立即终止整个通信,真实业务请求根本不会被发送到网络层。 - 服务端响应中缺少
Access-Control-Allow-Headers:即使服务端正确响应了 OPTIONS(返回 204/200),但如果其返回的响应头中没有显式包含客户端申请的自定义 Header 名称(例如没有返回Access-Control-Allow-Headers: X-Token, Authorization),浏览器在比对后会判定服务端拒绝该字段,并在控制台抛出经典报错:Request header field x-token is not allowed by Access-Control-Allow-Headers in preflight response.。
二、携带 Cookie 为何失败:必须同时跨过的“四重门槛”
相比自定义 Header,跨域携带 Cookie 的机制更加严苛。Cookie 本身是浏览器维护在特定域名下的敏感状态凭据,极易被利用于跨站请求伪造(CSRF)。为了防止恶意网站悄悄借用用户的身份 Cookie 窃取或篡改第三方接口数据,浏览器和 CORS 规范构筑了环环相扣的“四重门槛”。
门槛一:前端必须主动开启凭据传递开关
默认情况下,浏览器出于隐私保护考量,在发送跨域 Ajax 请求时是坚决不附加 Cookie 的:
- 在原生的
fetch API中,credentials选项的默认值是'same-origin'(仅在同源时发送 Cookie),跨域时会被自动剔除。必须显式指定为credentials: 'include'。 - 在
XMLHttpRequest或封装库(如 Axios)中,withCredentials属性默认值为false。必须显式设为xhr.withCredentials = true。
注意:如果前端遗漏了这个配置,网络请求可以正常发出并成功返回,控制台甚至不会报任何错误,但后端服务在日志中会发现 Cookie 请求头完全缺失,导致会话验证始终处于未登录状态。
门槛二:服务端严禁配置通配符 Access-Control-Allow-Origin: *
这是最让初学者困惑的限制:普通请求跨域时,配置 Access-Control-Allow-Origin: * 就能轻松放行;但一旦前端开启了 credentials: 'include',请求立刻会报红崩溃。
CORS 规范强制规定:当跨域请求携带凭据(Credentials)时,服务端的 Access-Control-Allow-Origin 绝对不能设置为通配符 *。它必须指定为一个明确的、与请求头中 Origin 完全吻合的单一源(例如 https://client.example.com)。
如果在携带凭据时服务端依然返回了 *,现代浏览器会直接阻断该响应,并在控制台输出明确警告:
The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*' when the request's credentials mode is 'include'.
门槛三:服务端必须显式响应 Access-Control-Allow-Credentials: true
即使服务端将 Access-Control-Allow-Origin 设为了具体的合法域名,只要漏掉了 Access-Control-Allow-Credentials: true 这一响应头,浏览器依然会认为该接口不允许跨域暴露用户隐私数据。
在这种情况下,请求实际上已经到达了后端服务器,后端甚至已经执行了数据库操作并返回了响应体,但浏览器会在客户端接收端直接将数据“截胡”扣下,阻止 JavaScript 读取任何响应内容,并向控制台抛出凭据未授权错误。
门槛四:Cookie 自身的 SameSite 与 HTTPS 约束
跨越了前面三道 CORS 关卡后,还有一道属于现代浏览器 Cookie 安全管理机制的门槛:SameSite 策略。
自 Chrome 80 及后续所有主流浏览器起,未指定 SameSite 属性的 Cookie 会被默认视为 SameSite=Lax。在 Lax 策略下,所有由 JavaScript 异步发起的跨站点请求(Cross-Site XHR / fetch)一律禁止携带该 Cookie!
如果要让 Cookie 在跨域异步请求中正常附带,后端在下发 Set-Cookie 时必须满足两个硬性条件:
- 必须声明
SameSite=None(允许跨站携带)。 - 必须同时声明
Secure标记(即该 Cookie 只能通过 HTTPS 加密信道传输,普通 HTTP 协议会被浏览器直接丢弃或拒绝加载)。
三、关键机制对照:简单请求 vs 预检请求、普通跨域 vs 凭据跨域
为了帮助读者从全局掌握跨域失败的本质,我们将两组最容易混淆的运行状态在相同基准条件下进行横向对照:
| 对照维度 | 简单请求(普通无凭据) | 非简单请求(自定义 Header) | 凭据跨域(携带 Cookie) |
|---|---|---|---|
| 网络往返轮次 | 1 次(直接发送实际请求) | 2 次(先发 OPTIONS 预检,再发业务请求) | 视是否含自定义 Header 而定(通常为 2 次) |
| 服务端 Allow-Origin 要求 | 允许使用通配符 * |
允许使用通配符 *(当无凭据时) |
严禁通配符 *,必须是确切 Origin |
| 服务端 Allow-Headers 要求 | 无需配置该头部 | 必须显式声明客户端携带的所有自定义 Header | 若同时含自定义 Header,则同样必须显式声明 |
| 服务端 Allow-Credentials | 无需配置 | 无需配置 | 必须显式配置为 true |
| Cookie 发送状态 | 浏览器自动剥离,不随请求发送 | 浏览器自动剥离,不随请求发送 | 需满足 SameSite=None; Secure 且 HTTPS |
通过上表可以清晰看出:跨域配置不是一套通用规则包办到底的。许多项目在未引入 Token 认证前一切正常,一旦前端在请求拦截器中加上 Authorization,请求便从“简单请求”滑入“预检请求”;而在引入 Cookie 会话时,原先奏效的 * 通配符又成为导致失败的元凶。
四、真实代码与配置:前端发起与服务端响应模板
理解了原理后,我们通过前后端真实代码演示正确的配置步骤。
1. 前端 JavaScript 发送规范
在前端发起请求时,必须正确设置 headers 与凭据配置项:
// 示例:使用 fetch 发送带自定义 Header 与 Cookie 的跨域请求
const requestData = async () => {
try {
const response = await fetch('https://api.example.com/v1/user/profile', {
method: 'POST',
// 1. 设置自定义请求头(会触发 OPTIONS 预检请求)
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer token_xyz_123',
'X-Client-Version': '2.1.0'
},
// 2. 显式开启跨域携带 Cookie
credentials: 'include',
body: JSON.stringify({ userId: 10086 })
});
if (!response.ok) {
throw new Error(`HTTP 异常状态码: ${response.status}`);
}
const data = await response.json();
console.log('获取数据成功:', data);
} catch (err) {
console.error('请求失败,可能被 CORS 或网络策略拦截:', err);
}
};
若使用广泛流行的 Axios 库,配置方式如下:
// Axios 全局或单次请求配置
axios.post('https://api.example.com/v1/user/profile',
{ userId: 10086 },
{
headers: {
'Authorization': 'Bearer token_xyz_123',
'X-Client-Version': '2.1.0'
},
withCredentials: true // 开启跨域携带凭据
}
);
2. 服务端响应头模板(以 Nginx 反向代理为例)
服务端需要针对 OPTIONS 预检请求做快速响应(返回 204),并为所有受信任源动态返回单域名,同时声明允许的 Header 与 Credentials:
# Nginx 跨域反向代理标准配置示例
server {
listen 443 ssl;
server_name api.example.com;
location /v1/ {
# 1. 动态匹配信任的 Origin,禁止硬编码通配符 *
set $cors_origin "";
if ($http_origin ~* "^https://(client\.example\.com|admin\.example\.com)$") {
set $cors_origin $http_origin;
}
# 2. 针对预检请求 OPTIONS 快速放行并返回 204
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' $cors_origin always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
# 必须包含客户端发来的全部自定义 Header
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Client-Version' always;
# 允许携带凭据
add_header 'Access-Control-Allow-Credentials' 'true' always;
# 预检结果缓存 24 小时(86400秒),避免每次交互都重复发送 OPTIONS
add_header 'Access-Control-Max-Age' 86400 always;
add_header 'Content-Type' 'text/plain; charset=utf-8';
add_header 'Content-Length' 0;
return 204;
}
# 3. 针对实际业务请求的响应头配置
add_header 'Access-Control-Allow-Origin' $cors_origin always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
proxy_pass http://backend_upstream;
}
}
最佳实践提示:利用 Access-Control-Max-Age 可以指定预检请求的有效缓存时间(例如 86400 秒)。在缓存期内,相同的跨域请求不再重复发起 OPTIONS 探测,能大幅提升业务接口的响应速度并降低服务器 QPS 压力。
五、开发者工具实操:常见报错定位与排查步骤
当遇到跨域失败时,读者可按照以下步骤在浏览器的开发者工具(F12)中快速定位根因:
-
查看 Network(网络)面板中的请求列表:
首先观察是否出现了一条 Method 为
OPTIONS的请求。如果 OPTIONS 请求的状态码为404或405,说明后端接口网关未放行预检;如果 OPTIONS 请求标红且提示 CORS 错误,点击该请求并查看其Response Headers(响应头),检查是否遗漏了Access-Control-Allow-Headers。 -
核对 Console(控制台)的具体报错文案:
浏览器的控制台报错信息通常极为精准:
- 提示
must not be the wildcard '*':立即检查后端是否返回了*,将其改为回显客户端具体源。 - 提示
is not allowed by Access-Control-Allow-Headers:检查报错中提到的字段名称,在后端的允许列表里补充上该名称。 - 提示
header in the response is '' which must be 'true':说明后端未设置Access-Control-Allow-Credentials: true。
- 提示
-
排查 Cookie 是否被浏览器静默拦截(Cookies 面板):
在 Network 面板选中实际请求,切换到
Cookies子标签页。如果某项 Cookie 前面出现黄色感叹号图标,将鼠标悬停在上方,浏览器会直接提示被过滤的原因(例如:“This cookie was blocked because it had the 'SameSite=Lax' attribute...”)。此时需在后端颁发 Cookie 时补充SameSite=None; Secure属性,且确认通信全程运行在 HTTPS 之上。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。