Node.js后端怎么手动设置CORS响应头允许JS跨域

作者:栖木时间:2026-11-22 19:11:39浏览:659

详细讲解在Node.js原生http模块和Express框架中,如何不依赖第三方库手动设置CORS响应头放行前端JavaScript跨域请求,涵盖预检OPTIONS处理、携带凭证与常见报错排查。

Node.js 服务端开发 HTTP 协议 跨域安全规范 适用环境:Node.js 原生 HTTP / Express 4.x / 5.x
Node.js后端怎么手动设置CORS响应头允许JS跨域
图 0:Node.js 手动配置 CORS 响应头架构示意图
在 Node.js 后端开发中,若不借助第三方 npm 模块(如 cors),允许浏览器端 JavaScript 跨域访问的核心做法是:在服务端监听到请求后,手动通过 res.setHeader()(原生模块)或 res.header()(Express)向 HTTP 响应中写入以 Access-Control-Allow-* 开头的标准响应头。与此同时,必须针对浏览器自动发起的 OPTIONS 预检请求进行拦截,立即返回 204 No Content 状态码结束响应,从而放行复杂请求。

一、同源策略与 CORS 响应头的工作机制

跨域资源共享(CORS, Cross-Origin Resource Sharing)是浏览器同源策略(Same-Origin Policy)下的安全机制。同源指的是协议(Protocol)、域名(Domain)和端口号(Port)三者完全一致。当运行在 http://localhost:3000 的前端网页通过 JavaScript(如 fetch 或 axios)向 http://api.domain.com:8000 发起 HTTP 请求时,浏览器会判定该行为为跨域操作。

需要明确的是:跨域请求本身通常已经正常到达了 Node.js 服务端并被处理,只是浏览器在接收响应时,若未发现预期的 CORS 响应头,会出于安全策略拦截响应内容,并向前端控制台抛出熟悉的“CORS error”错误。因此,解决跨域的核心责任在服务端,服务端必须主动在响应中告知浏览器该来源域是受信任的。

在 W3C 标准中,跨域请求被分为两类:

  • 简单请求(Simple Request):满足请求方法为 GET、POST 或 HEAD,且 HTTP 请求头仅包含标准的 Accept、Accept-Language、Content-Language,且 Content-Type 仅限于 text/plain、multipart/form-data 或 application/x-www-form-urlencoded。此类请求浏览器会直接发送业务请求,服务端只需输出 Access-Control-Allow-Origin 即可。
  • 复杂请求(Preflighted Request):只要使用了 PUT、DELETE 等动词,或提交了 application/json 数据,或携带了自定义请求头(例如 Authorization 鉴权凭证),浏览器在正式发送业务数据前,会强制自动发送一次 HTTP 方法为 OPTIONS 的预检请求。服务端必须正确响应预检请求并返回允许的请求头与方法,浏览器才会正式发送后续的业务请求。
Node.js后端怎么手动设置CORS响应头允许JS跨域
图 1:浏览器跨域请求机制 —— 简单请求与复杂预检(OPTIONS)请求交互时序

二、原生 Node.js http 模块的手动配置实现

在没有任何框架依赖的纯 Node.js 环境中,我们利用原生内置的 http 模块创建服务。通过统一拦截请求,设置响应头,并针对 OPTIONS 方法直接中断返回,即可完成完备的 CORS 配置。

Node.js后端怎么手动设置CORS响应头允许JS跨域
图 2:原生 Node.js 处理 CORS 请求的分支判断与执行步骤

以下是具备生产完整性的原生 Node.js 手动跨域配置示例:

// server-native.js
const http = require('http');

const PORT = 8000;

// 允许访问的白名单来源域(生产环境建议使用具体域名,而非直接设为 *)
const ALLOWED_ORIGINS = [
  'http://localhost:3000',
  'http://127.0.0.1:5500',
  'https://web.yourdomain.com'
];

const server = http.createServer((req, res) => {
  // 1. 获取客户端的请求来源 Origin
  const clientOrigin = req.headers['origin'];

  // 2. 检查来源是否在白名单中(若允许任意站点访问,可直接设为 '*')
  if (clientOrigin && ALLOWED_ORIGINS.includes(clientOrigin)) {
    res.setHeader('Access-Control-Allow-Origin', clientOrigin);
  } else {
    // 设为公共开放或默认单域名
    res.setHeader('Access-Control-Allow-Origin', '*');
  }

  // 3. 设置允许的 HTTP 方法
  res.setHeader(
    'Access-Control-Allow-Methods',
    'GET, POST, PUT, DELETE, PATCH, OPTIONS'
  );

  // 4. 设置允许的请求头(包含 JSON 格式必须的 Content-Type 以及认证 Header)
  res.setHeader(
    'Access-Control-Allow-Headers',
    'Content-Type, Authorization, X-Requested-With, Accept'
  );

  // 5. 设置预检请求结果的缓存有效期(单位为秒,86400 即 24 小时)
  res.setHeader('Access-Control-Max-Age', '86400');

  // 6. 关键步骤:拦截预检请求 (OPTIONS)
  if (req.method === 'OPTIONS') {
    // 预检请求只需要确认策略,不需要返回实体内容,标准响应码为 204 No Content
    res.writeHead(204);
    res.end();
    return;
  }

  // 7. 正常业务路由处理
  if (req.url === '/api/user' && req.method === 'GET') {
    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
    res.end(JSON.stringify({ code: 0, message: '跨域请求成功', data: { name: '张三' } }));
    return;
  }

  // 404 处理
  res.writeHead(404, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ code: 404, message: '接口未找到' }));
});

server.listen(PORT, () => {
  console.log(`原生 Node.js 服务已启动,监听端口: ${PORT}`);
});
代码关键点:注意第 34 行的 if (req.method === 'OPTIONS') 逻辑。许多初学者手动写响应头时容易漏掉这步,导致浏览器发送预检时进入了普通的业务路由或返回了 404,从而引发“预检请求失败(Response for preflight has invalid HTTP status code 404)”的报错。

三、CORS 响应头核心字段清单与参数解构

手动设置 CORS 并非只要写一行 Access-Control-Allow-Origin: * 就能应付所有场景。W3C 规范中定义了一组协作的响应头字段,分别承担不同维度的放行任务:

Node.js后端怎么手动设置CORS响应头允许JS跨域
图 3:Node.js 手动配置 CORS 的 6 个核心响应头及其适用场景矩阵
响应头名称 典型取值示例 作用与必须性说明
Access-Control-Allow-Origin * 或 http://localhost:3000 必选。指定允许跨域访问资源的来源。若涉及凭证必须反射具体域名,不可为 *。
Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS 预检必须。告知客户端哪些 HTTP 动词被允许调用,避免非法动词探测。
Access-Control-Allow-Headers Content-Type, Authorization 预检必须。放行客户端自定义的非简单请求头,若前端传了 Token 标头,后端必须显式加入该列表。
Access-Control-Allow-Credentials true 可选。指示跨域请求是否允许携带 Cookie 或身份凭据。只有布尔值 true 有效。
Access-Control-Max-Age 86400(秒) 强烈建议。将 OPTIONS 预检请求的结果缓存在浏览器中,避免每次发请求都进行一次多余的网络往返。
Access-Control-Expose-Headers X-Total-Count, Authorization 按需配置。默认情况下前端 JS 只能读取基本响应头。若需从响应读取自定义 Header,服务端需在此声明暴露。

四、Express 框架中编写自定义跨域中间件

在实际项目使用 Express 框架时,通常不需要安装第三方 cors 库,编写一个轻量级的全局中间件即可完全自主掌控跨域逻辑。

// server-express.js
const express = require('express');
const app = express();

const PORT = 8000;

// 支持携带 Cookie 时的安全白名单
const WHITE_LIST = [
  'http://localhost:3000',
  'http://localhost:5173',
  'https://admin.mydomain.com'
];

// 自定义 CORS 中间件
const manualCorsMiddleware = (req, res, next) => {
  const origin = req.headers.origin;

  // 1. 动态反射 Origin:如果来源在白名单内,动态设置其为响应头
  if (WHITE_LIST.includes(origin)) {
    res.header('Access-Control-Allow-Origin', origin);
  }

  // 2. 允许携带凭证(Cookie/Session)
  res.header('Access-Control-Allow-Credentials', 'true');

  // 3. 允许的动词与标头
  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
  res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept, Authorization');

  // 4. 预检缓存 1 小时 (3600 秒)
  res.header('Access-Control-Max-Age', '3600');

  // 5. 拦截 OPTIONS 预检请求并返回 204
  if (req.method === 'OPTIONS') {
    return res.sendStatus(204);
  }

  // 6. 普通请求流转至后续业务路由
  next();
};

// 在注册路由之前全局挂载中间件
app.use(manualCorsMiddleware);

// 解析 JSON 格式请求体
app.use(express.json());

// 业务路由示例
app.post('/api/login', (req, res) => {
  const { username } = req.body;
  res.json({
    code: 200,
    message: '登录成功',
    user: username || 'guest'
  });
});

app.listen(PORT, () => {
  console.log(`Express 服务启动成功: http://localhost:${PORT}`);
});
凭证跨域与通配符冲突陷阱:
当客户端配置了 credentials: 'include' 或 Axios 设置了 withCredentials = true 时,W3C 规范严正禁止服务端的 Access-Control-Allow-Origin 设置为 *。一旦同时出现,浏览器控制台会报错:
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'.
解决此问题的标准做法即如上述代码第 17 行所示:提取 req.headers.origin 并动态写回响应头。

五、前端验证、测试与排查决策树

配置完成后,在前端通过标准的 fetch 进行联调验证。以下前端代码演示了携带 JSON 与认证 Header 发送的典型复杂请求:

// 前端测试代码 (运行在 http://localhost:3000)
async function testCorsRequest() {
  try {
    const response = await fetch('http://localhost:8000/api/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer test-jwt-token-123456'
      },
      // 携带 Cookie 凭证
      credentials: 'include',
      body: JSON.stringify({ username: 'admin' })
    });

    const data = await response.json();
    console.log('跨域请求成功返回数据:', data);
  } catch (err) {
    console.error('跨域请求被拦截或网络错误:', err);
  }
}

testCorsRequest();
Node.js后端怎么手动设置CORS响应头允许JS跨域
图 4:Node.js 手动设置 CORS 响应头的决策全景与排查清单

常见排查指南与应对清单

  1. 在 Chrome 控制台 Network 面板排查:打开开发者工具 Network 标签,勾选“Preserve log”。如果存在复杂请求,先找到那条 Type 为 preflight 或 Method 为 OPTIONS 的记录,检查其 Response Headers 是否包含了 Access-Control-Allow-* 系列头且状态码为 204。
  2. 报错“Request header field authorization is not allowed by Access-Control-Allow-Headers”: 说明前端请求头里附带了 authorization,但后端响应头中只写了 Content-Type。必须将 Authorization 添加到服务端的 Access-Control-Allow-Headers 字段中。
  3. 前端 JS 使用 response.headers.get('token') 读不到自定义响应头: 虽然在 Network 面板能看到该 Header,但浏览器出于安全考虑默认对前端脚本屏蔽非标准标头。必须在 Node.js 端显式输出:
    res.setHeader('Access-Control-Expose-Headers', 'token, x-request-id');。
作者最新文章
相关文章
更多