深入解析 Fetch API 的 credentials 属性

引言

在现代 Web 开发中，Fetch API 已成为发起网络请求的标准方式。其中 credentials 属性控制着请求是否携带身份凭证（如 Cookie、HTTP 认证等），这直接关系到用户认证状态和跨域资源共享（CORS）的实现。

一、credentials 的三种配置模式

1. credentials: 'omit'

行为：从不发送任何凭证

适用场景：公开 API、静态资源请求

fetch('https://api.example.com/data', {
  credentials: 'omit'
})

2. credentials: 'same-origin'

行为：仅在同源请求时发送凭证

适用场景：同源 API 调用

fetch('/api/user', {
  credentials: 'same-origin'
})

3. credentials: 'include'

行为：总是发送凭证（包括跨域请求）

适用场景：跨域认证、单点登录(SSO)

fetch('https://auth.example.com/session', {
  credentials: 'include'
})

二、关键概念解析

1. 同源 vs 同站 vs 跨站

概念	判断标准	示例
同源	协议+域名+端口完全相同	https://app.com → https://app.com/api
同站	相同顶级域名（eTLD+1）	https://app.com → https://api.com
跨站	不同顶级域名	https://app.com → https://service.net

三、CORS 与 credentials 的关系

// 跨域请求 + credentials: 'include'
fetch('https://other-domain.com/api', {
  credentials: 'include',
  mode: 'cors'
})
// 需要服务器响应头包含 Access-Control-Allow-Credentials: true
// 且 Access-Control-Allow-Origin 不能使用 *（必须指定具体域名）

预检请求（Preflight Request）

当请求满足以下条件时会触发预检：

• 使用了 PUT、DELETE 等非简单方法
• 设置了自定义请求头
• Content-Type 不是以下三种之一：
  • application/x-www-form-urlencoded
  • multipart/form-data
  • text/plain

四、安全注意事项

1. 避免泄露凭证：跨域请求使用 credentials: 'include' 时，确保目标域名可信
2. CSRF 防护：使用 credentials 时，服务器应实现 CSRF Token 验证
3. Secure Cookie：生产环境应配合 Secure 和 SameSite 属性使用