Node.js后端怎么手动设置CORS响应头允许JS跨域
详细讲解在Node.js原生http模块和Express框架中,如何不依赖第三方库手动设置CORS响应头放行前端JavaScript跨域请求,涵盖预检OPTIONS处理、携带凭证与常见报错排查。
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 http 模块的手动配置实现
在没有任何框架依赖的纯 Node.js 环境中,我们利用原生内置的 http 模块创建服务。通过统一拦截请求,设置响应头,并针对 OPTIONS 方法直接中断返回,即可完成完备的 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}`);
});
if (req.method === 'OPTIONS') 逻辑。许多初学者手动写响应头时容易漏掉这步,导致浏览器发送预检时进入了普通的业务路由或返回了 404,从而引发“预检请求失败(Response for preflight has invalid HTTP status code 404)”的报错。
三、CORS 响应头核心字段清单与参数解构
手动设置 CORS 并非只要写一行 Access-Control-Allow-Origin: * 就能应付所有场景。W3C 规范中定义了一组协作的响应头字段,分别承担不同维度的放行任务:
| 响应头名称 | 典型取值示例 | 作用与必须性说明 |
|---|---|---|
| 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();
常见排查指南与应对清单
-
在 Chrome 控制台 Network 面板排查:打开开发者工具 Network 标签,勾选“Preserve log”。如果存在复杂请求,先找到那条 Type 为
preflight或 Method 为OPTIONS的记录,检查其 Response Headers 是否包含了Access-Control-Allow-*系列头且状态码为 204。 -
报错“Request header field authorization is not allowed by Access-Control-Allow-Headers”:
说明前端请求头里附带了
authorization,但后端响应头中只写了Content-Type。必须将Authorization添加到服务端的Access-Control-Allow-Headers字段中。 -
前端 JS 使用
response.headers.get('token')读不到自定义响应头: 虽然在 Network 面板能看到该 Header,但浏览器出于安全考虑默认对前端脚本屏蔽非标准标头。必须在 Node.js 端显式输出:
res.setHeader('Access-Control-Expose-Headers', 'token, x-request-id');。
基于Node.js的模块化汇编器项目架构设计指南
2026-11-22 18:03:22
Node.js中怎么读取本地JSON文件
2026-11-21 21:12:12
JS发送邮件报错535 Authentication failed怎么解决
2026-11-21 11:05:36
纯前端无后端依赖:JS 实现 Excel 文件导出的几种方案
2026-11-19 16:33:19
PHP中执行JavaScript代码的三种方案:v8js扩展、Node子进程与无头浏览器
2026-11-19 14:04:14








