JS发送带Cookie或自定义Header的跨域请求为何失败

作者:资源驿站

时间:2026-11-20

浏览:184

深入解析前端使用JavaScript(fetch或XMLHttpRequest)发送跨域请求时,因携带Cookie或自定义Header导致请求失败的核心原因、浏览器CORS预检机制、四重门槛检验与完整修复方案。

文章目录

在前端开发中,使用 JavaScript(fetch 或 XMLHttpRequest)向另一个源(协议、域名或端口不同)发送网络请求时,一旦在请求头中加入自定义字段(如 Authorization、X-Token)或开启 Cookie 传递,请求常常会在控制台直接抛出 CORS 错误。这一现象的核心根源在于:添加自定义 Header 会脱离浏览器的“简单请求”保护规范,强制触发 OPTIONS 预检请求,若服务端未正确放行该 Header 即会终止请求;而携带 Cookie 则触碰了浏览器的用户凭据安全红线,不仅前端必须主动声明开启凭据传输,服务端更被绝对禁止使用通配符(*)授权,且必须同时满足响应凭据许可与现代浏览器的第三方 Cookie 安全策略。

JS发送带Cookie或自定义Header的跨域请求为何失败
缩略概览图:JS 跨域请求中自定义 Header 与 Cookie 的浏览器安全审查机制全景

一、自定义 Header 为何失败:预检请求(Preflight)的拦截逻辑

在普通认知中,只要服务端配置了 Access-Control-Allow-Origin: *,跨域请求就能顺利通过。然而一旦在前端代码中添加了自定义请求头(例如用来传递身份凭据的 X-Token、Authorization,甚至是设置了 Content-Type: application/json),原本正常的请求就会立即失败。

这是因为 W3C 的跨域资源共享(CORS)规范将跨域请求严密划分为两类:简单请求(Simple Requests)与非简单请求(Preflighted Requests)。浏览器对这两类请求的处理策略存在本质差异。

JS发送带Cookie或自定义Header的跨域请求为何失败
图 1:浏览器跨域请求判定与预检(Preflight)决策推导流程

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)。
JS发送带Cookie或自定义Header的跨域请求为何失败
图 2:自定义 Header 预检请求与业务请求两阶段交互时序

此时,导致请求直接失败的常见阻断点集中在以下两处:

  1. 服务端未放行 OPTIONS 方法(返回 404 或 405):很多后端框架、网关或路由拦截器只定义了针对 GET 和 POST 路由的处理逻辑,遇到未知或未经注册的 OPTIONS 请求时,直接返回了 404 Not Found 或 405 Method Not Allowed。预检请求一旦没有得到成功的 HTTP 状态码(通常为 200 或 204),浏览器会立即终止整个通信,真实业务请求根本不会被发送到网络层。
  2. 服务端响应中缺少 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 规范构筑了环环相扣的“四重门槛”。

JS发送带Cookie或自定义Header的跨域请求为何失败
图 3:跨域携带 Cookie 必须同时满足的“四重门槛”验证模型

门槛一:前端必须主动开启凭据传递开关

默认情况下,浏览器出于隐私保护考量,在发送跨域 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)中快速定位根因:

JS发送带Cookie或自定义Header的跨域请求为何失败
图 4:跨域 Header 与 Cookie 失败特征、核心根因与修复动作矩阵
  1. 查看 Network(网络)面板中的请求列表:

    首先观察是否出现了一条 Method 为 OPTIONS 的请求。如果 OPTIONS 请求的状态码为 404 或 405,说明后端接口网关未放行预检;如果 OPTIONS 请求标红且提示 CORS 错误,点击该请求并查看其 Response Headers(响应头),检查是否遗漏了 Access-Control-Allow-Headers。

  2. 核对 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。
  3. 排查 Cookie 是否被浏览器静默拦截(Cookies 面板):

    在 Network 面板选中实际请求,切换到 Cookies 子标签页。如果某项 Cookie 前面出现黄色感叹号图标,将鼠标悬停在上方,浏览器会直接提示被过滤的原因(例如:“This cookie was blocked because it had the 'SameSite=Lax' attribute...”)。此时需在后端颁发 Cookie 时补充 SameSite=None; Secure 属性,且确认通信全程运行在 HTTPS 之上。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章