cors

CORS 是一个 Node.js 软件包，提供一个 Connect/Express 中间件，可用于启用具有各种选项的 CORS。

安装
用法
配置选项
许可证
作者

安装

这是一个可通过 npm 注册表获得的 Node.js 模块。使用 npm install 命令进行安装

$ npm install cors

用法

简单用法（启用所有 CORS 请求）

var express = require('express')
var cors = require('cors')
var app = express()

app.use(cors())

app.get('/products/:id', function (req, res, next) {
  res.json({msg: 'This is CORS-enabled for all origins!'})
})

app.listen(80, function () {
  console.log('CORS-enabled web server listening on port 80')
})

为单个路由启用 CORS

var express = require('express')
var cors = require('cors')
var app = express()

app.get('/products/:id', cors(), function (req, res, next) {
  res.json({msg: 'This is CORS-enabled for a Single Route'})
})

app.listen(80, function () {
  console.log('CORS-enabled web server listening on port 80')
})

配置 CORS

有关详细信息，请参阅配置选项。

var express = require('express')
var cors = require('cors')
var app = express()

var corsOptions = {
  origin: 'http://example.com',
  optionsSuccessStatus: 200 // some legacy browsers (IE11, various SmartTVs) choke on 204
}

app.get('/products/:id', cors(corsOptions), function (req, res, next) {
  res.json({msg: 'This is CORS-enabled for only example.com.'})
})

app.listen(80, function () {
  console.log('CORS-enabled web server listening on port 80')
})

配置带动态源的 CORS

此模块支持使用提供给 origin 选项的函数动态验证源。此函数将接收一个字符串作为源（如果请求没有源，则为 undefined），以及一个签名为 callback(error, origin) 的 callback。

callback 的 origin 参数可以是中间件 origin 选项允许的任何值，但不能是函数。有关所有可能的值类型，请参阅配置选项部分。

此函数旨在允许从后端数据源（如数据库）动态加载允许的源。

var express = require('express')
var cors = require('cors')
var app = express()

var corsOptions = {
  origin: function (origin, callback) {
    // db.loadOrigins is an example call to load
    // a list of origins from a backing database
    db.loadOrigins(function (error, origins) {
      callback(error, origins)
    })
  }
}

app.get('/products/:id', cors(corsOptions), function (req, res, next) {
  res.json({msg: 'This is CORS-enabled for an allowed domain.'})
})

app.listen(80, function () {
  console.log('CORS-enabled web server listening on port 80')
})

启用 CORS 预检

某些 CORS 请求被认为是“复杂”的，需要初始的 OPTIONS 请求（称为“预检请求”）。“复杂”CORS 请求的一个例子是使用 GET/HEAD/POST 之外的 HTTP 动词（例如 DELETE）或使用自定义头部的请求。要启用预检，您必须为您要支持的路由添加一个新的 OPTIONS 处理程序

var express = require('express')
var cors = require('cors')
var app = express()

app.options('/products/:id', cors()) // enable pre-flight request for DELETE request
app.del('/products/:id', cors(), function (req, res, next) {
  res.json({msg: 'This is CORS-enabled for all origins!'})
})

app.listen(80, function () {
  console.log('CORS-enabled web server listening on port 80')
})

您也可以像这样全面启用预检

app.options('*', cors()) // include before other routes

注意：当将此中间件用作应用程序级别中间件时（例如，app.use(cors())），预检请求已经为所有路由处理。

按请求动态自定义 CORS 设置

对于需要针对特定路由或请求设置不同 CORS 配置的 API，您可以根据传入请求动态生成 CORS 选项。cors 中间件允许您通过传递函数而不是静态选项来实现此目的。此函数会在每个传入请求时被调用，并且必须使用回调模式返回适当的 CORS 选项。

该函数接受

req:
- 传入请求对象。
callback(error, corsOptions):
- 用于返回计算出的 CORS 选项的函数。
- 参数:
  - error：如果没有错误，则传递 null；如果出现故障，则传递错误对象。
  - corsOptions：一个对象，指定当前请求的 CORS 策略。

这是一个处理公共路由和受限、凭据敏感路由的示例

var dynamicCorsOptions = function(req, callback) {
  var corsOptions;
  if (req.path.startsWith('/auth/connect/')) {
    corsOptions = {
      origin: 'http://mydomain.com', // Allow only a specific origin
      credentials: true,            // Enable cookies and credentials
    };
  } else {
    corsOptions = { origin: '*' };   // Allow all origins for other routes
  }
  callback(null, corsOptions);
};

app.use(cors(dynamicCorsOptions));

app.get('/auth/connect/twitter', function (req, res) {
  res.send('CORS dynamically applied for Twitter authentication.');
});

app.get('/public', function (req, res) {
  res.send('Public data with open CORS.');
});

app.listen(80, function () {
  console.log('CORS-enabled web server listening on port 80')
})

配置选项

origin: 配置 Access-Control-Allow-Origin CORS 头部。可能的值
- Boolean - 将 origin 设置为 true 以反映请求源（由 req.header('Origin') 定义），或将其设置为 false 以禁用 CORS。
- String - 将 origin 设置为特定源。例如，如果将其设置为
  - "http://example.com" 则只允许来自“http://example.com”的请求。
  - "*" 允许所有域。
- RegExp - 将 origin 设置为正则表达式模式，该模式将用于测试请求源。如果匹配，则请求源将被反映。例如，模式 /example\.com$/ 将反映来自以“example.com”结尾的源的任何请求。
- Array - 将 origin 设置为有效源数组。每个源可以是 String 或 RegExp。例如 ["http://example1.com", /\.example2\.com$/] 将接受来自“http://example1.com”或“example2.com”子域的任何请求。
- Function - 将 origin 设置为实现某些自定义逻辑的函数。该函数将请求源作为第一个参数，并将一个回调（调用为 callback(err, origin)，其中 origin 是 origin 选项的非函数值）作为第二个参数。
methods：配置 Access-Control-Allow-Methods CORS 头部。期望一个逗号分隔的字符串（例如：“GET,PUT,POST”）或一个数组（例如：['GET', 'PUT', 'POST']）。
allowedHeaders：配置 Access-Control-Allow-Headers CORS 头部。期望一个逗号分隔的字符串（例如：“Content-Type,Authorization”）或一个数组（例如：['Content-Type', 'Authorization']）。如果未指定，则默认为反映请求的 Access-Control-Request-Headers 头部中指定的头部。
exposedHeaders：配置 Access-Control-Expose-Headers CORS 头部。期望一个逗号分隔的字符串（例如：“Content-Range,X-Content-Range”）或一个数组（例如：['Content-Range', 'X-Content-Range']）。如果未指定，则不暴露任何自定义头部。
credentials：配置 Access-Control-Allow-Credentials CORS 头部。设置为 true 以传递此头部，否则省略。
maxAge：配置 Access-Control-Max-Age CORS 头部。设置为整数以传递此头部，否则省略。
preflightContinue：将 CORS 预检响应传递给下一个处理程序。
optionsSuccessStatus：为成功的 OPTIONS 请求提供一个状态码，因为一些旧浏览器（IE11、各种智能电视）在 204 时会出现问题。

默认配置等同于

{
  "origin": "*",
  "methods": "GET,HEAD,PUT,PATCH,POST,DELETE",
  "preflightContinue": false,
  "optionsSuccessStatus": 204
}

有关每个 CORS 头部影响的详细信息，请阅读 web.dev 上的这篇文章。

许可证

MIT 许可证

作者

Troy Goode ([email protected])