深入解析JavaScript跨域请求携带Cookie及Credentials凭证的完整实现方案。包含Fetch、XMLHttpRequest与Axios的前端配置、后端CORS响应头设置、预检请求处理、Cookie的SameSite安全属性限制与常见报错排查。
JS跨域请求怎么携带Cookie和Credentials凭证
时间:2026-11-20
浏览:218
文章目录
credentials: 'include' 或 withCredentials = true),服务端严格配置 CORS 响应头允许凭据且声明具体的客户端源(严禁使用通配符 *),同时目标 Cookie 必须具备 SameSite=None; Secure 跨站放行属性。
一、跨域凭证的运作原理与双向准入机制
在同源策略下,网页发起向自身域名的请求会自动带上该域名下的所有有效 Cookie。然而,当网页所在源(例如 https://app.example.com)向不同源(例如 https://api.service.com)发起异步网络请求(Fetch 或 XMLHttpRequest)时,浏览器将此视为跨域子请求。
Credentials(凭证)在 Web 规范中涵盖 HTTP Cookie、HTTP Basic/Digest 认证头以及 TLS 客户端证书。如果浏览器无条件允许前端脚本向任意第三方接口发送 Cookie,攻击者就可以通过恶意网页诱导用户浏览器发起携带登录态凭据的请求,造成严重的数据泄露或跨站请求伪造(CSRF)。
因此,现代 Web 规范确立了“双向确认 + 浏览器沙箱核验”的双重门禁准则:
- 发起端意图确认:前端代码必须明确声明当前请求允许包含凭据,避免因代码疏忽在普通跨域资源探测中泄露敏感凭证。
- 接收端准入许可:目标服务端必须在响应中显式返回响应头
Access-Control-Allow-Credentials: true,并明确将Access-Control-Allow-Origin指向当前发起请求的具体源,禁止任何泛域名通配。 - 终端门禁裁决:如果服务端未返回上述凭证许可,浏览器安全沙箱会立即在底层销毁服务端返回的数据包,并向前端运行时抛出错误,阻止前端 JavaScript 访问任何响应体或响应头。
二、前端客户端的凭证配置步骤与完整实现
浏览器提供了多种发起网络请求的方式,不同 API 在设置携带凭证时的语法与默认行为有所区别。以下分别说明 Fetch API、原生 XMLHttpRequest 以及工程中高频使用的 Axios 的配置方法。
1. Fetch API 的凭证配置
Fetch API 通过请求配置项中的 credentials 字段控制凭证行为。该字段包含三个可选枚举值:
'omit':忽略所有凭据,即使同源请求也不发送 Cookie,且不读取响应中的 Set-Cookie。'same-origin':默认值。仅在同源请求时附带 Cookie,在跨域请求时自动剔除。'include':跨域与同源请求均附带 Cookie,并允许在响应中处理 Set-Cookie。
在跨域场景下,必须将 credentials 设置为 'include':
// 环境:现代主流浏览器执行环境
// 执行位置:前端业务模块或数据请求层
async function fetchUserProfile() {
const targetUrl = 'https://api.service.com/v1/user/profile';
try {
const response = await fetch(targetUrl, {
method: 'GET',
// 关键设置:跨域携带凭证必须显式声明为 include
credentials: 'include',
headers: {
'Accept': 'application/json'
}
});
if (!response.ok) {
throw new Error(`HTTP 请求异常: ${response.status}`);
}
const data = await response.json();
console.log('获取用户信息成功:', data);
return data;
} catch (error) {
// 若服务端 CORS 凭据头配置不匹配,此处捕获 TypeError: Failed to fetch
console.error('跨域凭证请求失败:', error);
}
}
2. XMLHttpRequest 的凭证配置
对于使用原生 XMLHttpRequest 的项目,必须在调用 xhr.send() 之前将实例的 withCredentials 属性赋值为布尔值 true。其默认值为 false。
// 原生 XMLHttpRequest 跨域携带凭证标准示例
function loadDataByXHR() {
const xhr = new XMLHttpRequest();
const targetUrl = 'https://api.service.com/v1/user/profile';
xhr.open('GET', targetUrl, true);
// 关键设置:开启跨域凭据支持
xhr.withCredentials = true;
xhr.onreadystatechange = function () {
if (xhr.readyState === XMLHttpRequest.DONE) {
if (xhr.status === 200) {
console.log('响应数据:', JSON.parse(xhr.responseText));
} else {
console.error('请求失败或被 CORS 策略阻断, 状态码:', xhr.status);
}
}
};
xhr.send();
}
3. Axios 请求库的配置
Axios 基于 XMLHttpRequest 或 Fetch 封装。在 Axios 中,可以在发起单独请求时传递 withCredentials: true,也可以通过全局默认配置或 Axios 实例进行统一声明。
import axios from 'axios';
// 方式一:创建带有凭证配置的专用 Axios 实例(推荐)
const apiClient = axios.create({
baseURL: 'https://api.service.com/v1',
timeout: 8000,
// 关键设置:所有通过该实例发出的请求均携带 Cookie
withCredentials: true,
headers: {
'Content-Type': 'application/json'
}
});
// 方式二:全局默认设置(对所有 axios 调用生效)
// axios.defaults.withCredentials = true;
async function requestDashboard() {
try {
const res = await apiClient.get('/dashboard');
return res.data;
} catch (err) {
console.error('业务接口调用异常:', err.message);
}
}
三、服务端 CORS 响应头配置与预检请求处理
无论前端如何设置,如果目标接口的服务端没有做出符合规范的响应头承诺,浏览器绝不会向脚本交付数据。服务端配置跨域凭据时有两大核心铁律与预检要求。
1. 响应头两大核心规则
credentials: 'include' 或 withCredentials: true)时,服务端的 Access-Control-Allow-Origin 绝对不能设置为通配符 *。若设置为通配符,浏览器控制台会直接报错并拒收响应。
服务端必须返回以下两个核心响应头:
Access-Control-Allow-Credentials: true:明确告知浏览器当前接口接受并信任跨域凭证。Access-Control-Allow-Origin: https://app.example.com:必须是当前发起请求的确切客户端源(包含协议、域名和端口)。若需要支持多个不同前端域名,服务端应动态提取请求头中的Origin,校验该源是否在系统白名单内,若合法则将其值原样反射回写在Access-Control-Allow-Origin中,并附带Vary: Origin标头。
2. 复杂请求与 OPTIONS 预检机制
当跨域请求包含自定义请求头(如 Authorization、X-Request-Id)、使用了除 GET、POST、HEAD 之外的方法(如 PUT、DELETE),或者 Content-Type 为 application/json 时,浏览器会先发出一次 OPTIONS 方法的预检请求(Preflight Request)。
注意:预检请求本身按 W3C 规范不携带 Cookie,但服务端在回应预检请求时,必须同样附带 Access-Control-Allow-Credentials: true、对应的 Access-Control-Allow-Origin、以及允许的方法与头部列表,状态码建议返回 204 No Content。
3. 典型服务端实现示例
以下为 Node.js (Express) 与 Nginx 反向代理两种常见环境的配置代码:
// 运行环境:Node.js (Express) 服务端
// 文件位置:server/app.js
const express = require('express');
const app = express();
// 允许跨域携带凭据的前端源白名单列表
const allowedOrigins = [
'https://app.example.com',
'https://admin.example.com'
];
app.use((req, res, next) => {
const origin = req.headers.origin;
if (allowedOrigins.includes(origin)) {
// 1. 精确回写匹配的源,不使用通配符
res.setHeader('Access-Control-Allow-Origin', origin);
// 2. 声明允许凭据
res.setHeader('Access-Control-Allow-Credentials', 'true');
// 3. 避免不同客户端缓存串扰
res.setHeader('Vary', 'Origin');
}
// 4. 预检请求专有处理
if (req.method === 'OPTIONS') {
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');
res.setHeader('Access-Control-Max-Age', '86400'); // 预检缓存24小时
return res.sendStatus(204);
}
next();
});
若通过 Nginx 进行反向代理与统一跨域头管理:
# Nginx 配置文件片段 (nginx.conf / vhost.conf)
server {
listen 443 ssl;
server_name api.service.com;
# 动态匹配合法的客户端 Origin
set $cors_origin "";
if ($http_origin ~* "^https?://(app\.example\.com|admin\.example\.com)$") {
set $cors_origin $http_origin;
}
location / {
if ($cors_origin != "") {
add_header 'Access-Control-Allow-Origin' $cors_origin always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
add_header 'Vary' 'Origin' always;
}
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' $cors_origin always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization, X-Requested-With' always;
add_header 'Access-Control-Max-Age' 86400 always;
add_header 'Content-Type' 'text/plain; charset=utf-8';
add_header 'Content-Length' 0;
return 204;
}
proxy_pass http://backend_upstream;
}
}
四、Cookie 自身的安全属性与浏览器策略限制
即使前后端在代码层面都正确声明了凭据参数与响应头,请求仍可能由于目标 Cookie 本身的安全属性不合规而被浏览器内核直接过滤。理解现代浏览器对第三方 Cookie 的策略是确保凭证成功传输的必要条件。
1. SameSite 属性与跨站点子请求
Cookie 的 SameSite 属性用于控制在跨站点(Cross-Site)请求时是否发送 Cookie。现代浏览器默认将未设置 SameSite 的 Cookie 视同为 SameSite=Lax。
SameSite=Strict:完全禁止在任何跨站请求中发送 Cookie(包括链接点击跳转)。SameSite=Lax:在跨站的普通链接导航(如<a href>、顶层 GET 导航)中允许携带,但严格禁止在跨站异步请求(Fetch / XHR)中携带。SameSite=None:允许在跨站点上下文中发送 Cookie。
Set-Cookie 写入时,必须显式附加 SameSite=None; Secure。并且由于声明了 Secure,整个通信链路必须基于 HTTPS 协议进行(本地开发 localhost 通常作为特例豁免)。
2. HttpOnly 属性与作用域(Domain / Path)
很多开发者容易混淆 HttpOnly 的影响。实际上,HttpOnly 仅禁止前端 JavaScript 通过 document.cookie 读取该 Cookie,并不会阻碍浏览器在网络层发起请求时自动携带它。将认证 Cookie 设为 HttpOnly 既能满足跨域携带登录凭证的需求,又能有效防范 XSS 窃取,是生产环境的推荐安全实践。
此外,Cookie 的 Domain 和 Path 必须覆盖当前请求接口的 Host 与路径。例如,若请求发送至 api.service.com/v1,而 Cookie 的 Domain 设置为 auth.service.com,浏览器自然不会将其作为匹配凭证附带。
| Cookie 属性组合 | 传输协议环境 | 跨域 Ajax 请求携带表现 | 安全性与合规判定 |
|---|---|---|---|
SameSite=Lax 或未显式设置 |
HTTP / HTTPS | 被拦截(不发送 Cookie) | 默认策略,仅同站点或顶层导航可用 |
SameSite=None(未加 Secure) |
HTTP / HTTPS | 被拒收(浏览器直接丢弃该 Cookie) | 违反安全规范,现代浏览器强制校验失败 |
SameSite=None; Secure |
HTTPS | 正常携带 | 跨域凭证标准配置,符合安全传输规范 |
SameSite=None; Secure; HttpOnly |
HTTPS | 正常携带(JS 不可读,网络层自动注入) | 生产最佳推荐,兼顾跨域认证与防 XSS 攻击 |
五、常见异常排查与端到端验证指南
在实际项目落地过程中,跨域凭证配置往往涉及网关、后端微服务和前端多个层级,容易出现某一个环节漏设导致整体失败。以下整理了四种最常见的报错现象及其根因排查步骤。
1. 控制台报错:通配符 '*' 与凭证模式冲突
错误信息示例:
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'.
排查及修复:检查后端服务或 Nginx 代理配置,找到 Access-Control-Allow-Origin * 并修改。修改为从请求头 Origin 获取来源,判断在白名单后动态回写客户端的确切源。
2. 请求执行成功但请求头中没有 Cookie
排查及修复:
- 打开浏览器开发者工具(F12),切换至 Application / Storage -> Cookies,检查目标服务端域名下是否存在对应的 Cookie 记录。
- 查看该 Cookie 的
SameSite列与Secure标识。如果显示为Lax、空值或未勾选Secure,说明是服务端下发 Cookie 时的属性有误。 - 在 Network 面板中点击该请求,查看其 Cookies 子选项卡。现代 Chrome / Edge 会用黄色叹号直接标明该 Cookie 为何未附带(例如:“This cookie was blocked because of SameSite status”)。
- 确认前端代码中是否遗漏了
credentials: 'include'或withCredentials: true。
3. 预检请求 OPTIONS 报 401 Unauthorized 或 403 Forbidden
排查及修复:后端权限拦截器(如 Spring Security、Shiro 或自定义鉴权中间件)对所有 HTTP 请求一视同仁进行了身份验证,而预检请求 OPTIONS 本身不会带任何 Cookie 或自定义鉴权头。解决方法是在服务端过滤器或网关最外层直接放行所有 OPTIONS 请求并返回 204 状态码,使预检顺利通过。
4. 出现“Multiple values for header Access-Control-Allow-Origin”冲突
排查及修复:通常发生在使用 Nginx 反向代理 Node/Java 服务的架构中。Node/Java 应用代码中通过 CORS 中间件添加了该头,而 Nginx 配置中又通过 add_header 增加了一次,导致响应中存在两个 Access-Control-Allow-Origin 值。只需保留其中一处配置即可。
- 前端请求参数已显式配置凭据模式(
include/withCredentials = true)。 - 服务端响应头
Access-Control-Allow-Origin为具体发起端域名,并非*。 - 服务端响应头明确输出
Access-Control-Allow-Credentials: true。 - Cookie 属性包含
SameSite=None; Secure,全流程在 HTTPS 安全上下文下运行。 - 预检请求(OPTIONS)放行无阻且正确返回上述 CORS 凭证授权头。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。