引言：每个前端都见过的那行红字#

如果你做过前后端分离的项目，几乎一定在控制台见过它：

1
Access to fetch at 'https://api.example.com/api/users' from origin
2
'https://app.example.com' has been blocked by CORS policy:
3
No 'Access-Control-Allow-Origin' header is present on the requested resource.

这就是跨域问题。它出现的频率极高，却总被当作「后端没配好」一笔带过。这篇文章把 CORS 的机制从头拆开，再落到三种后端框架的配置和排查上，让你下次看到这行红字时不再靠「加个 *」碰运气。

一、前置概念：同源策略#

浏览器有一个铁律——同源策略（Same-Origin Policy）。它规定：一个页面里的脚本，只能读取「同源」资源的响应。

「同源」的判定标准是三个部分完全一致：协议（scheme）+ 主机（host）+ 端口（port）。三者任一不同，就是跨域：

注意路径、查询参数都不参与同源判定——/a 和 /b 永远是同源的。

同源策略存在的意义是安全：没有它，任何网站都能用你的 Cookie 去请求你的网银、邮箱并读取结果。它是浏览器安全的基石，但同时也挡住了「合法」的前后端分离场景——前端跑在 localhost:5173，后端跑在 localhost:3000，端口不同就是跨域。

CORS（Cross-Origin Resource Sharing，跨源资源共享）就是浏览器为「合法跨域」开的一扇门：由服务器通过响应头明确声明「哪些来源可以访问我」。

二、两种请求：简单请求 vs 预检请求#

CORS 把跨域请求分成两类，处理方式完全不同，这是理解一切报错的关键。

简单请求（Simple Request）——同时满足以下条件，浏览器直接发请求：

• 方法为 GET、HEAD、POST 之一；
• 只使用「安全名单」里的请求头，如 Accept、Accept-Language、Content-Language，以及取值限于 application/x-www-form-urlencoded、multipart/form-data、text/plain 的 Content-Type；
• 没有使用 ReadableStream、XMLHttpRequest.upload 事件监听等。

简单请求不会触发额外请求，浏览器只是「先斩后奏」——请求照发，但响应能不能被脚本读到，取决于返回头里有没有 Access-Control-Allow-Origin。

预检请求（Preflight Request）——只要不满足上面任意一条，浏览器就会先发一个 OPTIONS 请求「探路」：

1
OPTIONS /api/users HTTP/1.1
2
Origin: https://app.example.com
3
Access-Control-Request-Method: PUT
4
Access-Control-Request-Headers: content-type, authorization

服务器必须对这个 OPTIONS 返回允许的方法和头，浏览器才会放行真正的请求。这就是为什么你在 Network 面板里常看到同一个接口出现两次请求、一次是 OPTIONS。

三、关键响应头一览#

CORS 的配置本质上就是设置下面这几个响应头：

有两个容易忽略的点：

1. Access-Control-Expose-Headers 管的是「读响应头」。默认情况下，跨域响应的 Content-Type、Cache-Control 等少数头可以被 JS 读到，但你自定义的 X-Total-Count、X-RateLimit-Remaining 等是读不到的——除非在 Access-Control-Expose-Headers 里列出来。

2. Access-Control-Max-Age 管的是「预检缓存」。预检请求本身有开销，浏览器会缓存预检结果，最长缓存 Access-Control-Max-Age 指定的秒数（Chromium 实际上限约 2 小时）。这既是性能优化，也是「改了配置却不生效」的常见元凶。

四、服务端实战配置#

1
const express = require('express');
2
const cors = require('cors');
3

4
const app = express();
5

6
app.use(cors({
7
  // 只放行明确的白名单，而不是无脑用 *
8
  origin: ['https://app.example.com', 'https://admin.example.com'],
9
  credentials: true,                 // 允许带 Cookie
10
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
11
  exposedHeaders: ['X-Total-Count'],
12
  maxAge: 3600,                      // 预检结果缓存 1 小时
13
}));
14

15
app.get('/api/users', (req, res) => {
16
  res.set('X-Total-Count', '42');    // 需要 expose 才能被前端读到
17
  res.json([{ id: 1, name: 'Alice' }]);
18
});
19

20
app.listen(3000);

1
const http = require('http');
2

3
const ALLOWED = new Set(['https://app.example.com']);
4

5
const server = http.createServer((req, res) => {
6
  const origin = req.headers.origin;
7

8
  // 1. 处理预检请求
9
  if (req.method === 'OPTIONS') {
10
    const allowOrigin = ALLOWED.has(origin) ? origin : '';
11
    res.writeHead(204, {
12
      'Access-Control-Allow-Origin': allowOrigin,
13
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
14
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
15
      'Access-Control-Allow-Credentials': 'true',
16
      'Access-Control-Max-Age': '3600',
17
      'Vary': 'Origin',
18
    });
19
    res.end();
20
    return;
21
  }
22

23
  // 2. 普通请求：来源在白名单内才放行
24
  if (origin && ALLOWED.has(origin)) {
25
    res.setHeader('Access-Control-Allow-Origin', origin);
26
    res.setHeader('Access-Control-Allow-Credentials', 'true');
27
    res.setHeader('Vary', 'Origin');
28
  }
29

30
  res.setHeader('Content-Type', 'application/json');
31
  res.end(JSON.stringify({ ok: true }));
32
});
33

34
server.listen(3000);

1
location /api/ {
2
    if ($http_origin ~* "^https://(app|admin)\.example\.com$") {
3
        add_header 'Access-Control-Allow-Origin' "$http_origin" always;
4
        add_header 'Access-Control-Allow-Credentials' 'true' always;
5
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
6
        add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
7
        add_header 'Access-Control-Max-Age' '3600' always;
8
        add_header 'Vary' 'Origin' always;
9
    }
10

11
    if ($request_method = 'OPTIONS') {
12
        return 204;
13
    }
14
}

五、带凭证（Cookie）的跨域#

默认情况下，跨域请求不会携带 Cookie。如果接口依赖 Cookie 做会话，需要两端配合：

前端：fetch 里设 credentials: 'include'（或 axios 里设 withCredentials: true）：

1
fetch('https://api.example.com/api/me', {
2
  credentials: 'include',
3
})
4
  .then((res) => res.json())
5
  .then((data) => console.log(data));

后端：必须回显具体的 origin，并加 Access-Control-Allow-Credentials: true。

这里有一个高频陷阱：带凭证时，Access-Control-Allow-Origin 不能是 *。规范要求「要么回显具体来源，要么不能带凭证」，二者互斥。你会在控制台看到这样一条明确的报错：

1
The value of the 'Access-Control-Allow-Origin' header in the response
2
must not be the wildcard '*' when the request's credentials mode is 'include'.

解决办法就是前面示例里的白名单回显写法：拿到 Origin，判断是否在白名单，是则原样回显。

六、经典报错对照表#

排查时还有两个「真相」值得记牢：

1. CORS 是浏览器行为，不是服务器行为。用 curl 或 Postman 请求接口永远「通」，因为它们根本不执行同源策略。所以「Postman 能通、浏览器不通」不代表后端坏了，只能说明 CORS 头没配。

2. 简单请求是「发了但读不到」。浏览器把请求发出去了，服务器也处理了，只是响应被浏览器拦下不交给 JS。所以简单请求的跨域问题，看 Network 面板里请求是成功的（200），但控制台报 CORS——别被「请求成功了呀」误导。

七、两个进阶陷阱#

陷阱一：null origin。

当页面从 file:// 协议打开，或位于 sandbox 的 iframe 里时，请求的 Origin 头是字符串 "null"。如果你的白名单是 Set(['https://app.example.com'])，它当然不匹配——但有些粗心的配置会写 origin: 'null' 来「放行」，这其实等于向任何从 file:// 打开的恶意本地页面敞开了大门，是安全隐患。正确做法是不要接受 null 作为可信来源。

陷阱二：盲目 * 的代价。

开发时图省事写 Access-Control-Allow-Origin: * 确实能立刻让报错消失，但它同时意味着任何网站都能读取该接口的公开响应。对于纯公开、不涉及凭证和敏感数据的接口（如公共 API、静态资源）* 是可以接受的；一旦接口涉及用户数据，就应该用白名单。

结语#

CORS 的难点从来不在「加个头」——而在理解它背后的三个层次：同源策略为什么要拦、简单请求和预检请求的区别、以及浏览器 vs 服务器的责任边界。理清这三点，绝大多数跨域报错都能在五分钟内定位。

一个实用的收尾建议：开发期与其到处配 CORS，不如用前端 dev server 的代理把 /api 转发到后端（Vite、webpack、CRA 都内置了 proxy 配置），让浏览器视角里前后端「同源」，从根上绕过跨域；生产环境再老老实实在网关层配好白名单。这样开发体验干净，生产又安全。

参考来源#

• MDN - Cross-Origin Resource Sharing (CORS)
• MDN - Same-origin policy
• RFC 6454 - The Web Origin Concept
• Fetch 规范 - CORS protocol
• cors - Node.js 中间件官方文档
• web.dev - 从浏览器看 CORS 与安全性