# CORS 配置选项

cors 插件启用跨源资源共享，允许服务器指定获准的来源，并指示浏览器从这些来源加载资源，从而提高 API 的可访问性。<!-- --> <!-- -->配置涵盖插件参数和插件元数据。

## 参数[​](#参数 "参数的直接链接")

请参阅插件[通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)，了解所有插件通用的配置选项。

* allow\_origins

  string

  默认值：`*`

  ***

  允许 CORS 的来源，用逗号分隔的字符串。

  如果 `allow_credential` 设置为 `true`，你可以通过将该字段配置为 `**` 来强制允许所有来源的 CORS，但敏感数据（如身份认证 Token 或 cookie）可能会暴露给任何恶意网站。

  你还可以使用[插件元数据](https://docs.apiseven.com/apisix/key-concepts/plugin-metadata.md)在全局范围内配置允许来源，这会配置所有 `cors` 插件实例的允许来源。有关更多详细信息，请参阅[示例](https://docs.apiseven.com/hub/cors.md#在插件元数据中配置来源)。

* allow\_methods

  string

  默认值：`*`

  ***

  允许 CORS 的 HTTP 请求方法，用逗号分隔的字符串。

  如果 `allow_credential` 设置为 `true`，你可以通过将该字段配置为 `**` 来强制允许所有方法的 CORS，但恶意行为者可以使用 HTTP 方法（如 `PUT` 或 `DELETE`）对共享资源进行意外修改并构成安全威胁。

* allow\_headers

  string

  默认值：`*`

  ***

  允许在请求中使用的 HTTP 头，用逗号分隔的字符串。

  如果 `allow_credential` 设置为 `true`，你可以通过将该字段配置为 `**` 来强制允许所有请求头的 CORS，但这可能会允许向服务器发送恶意头。

* expose\_headers

  string

  ***

  应该在响应跨源请求时提供的 HTTP 头，用逗号分隔的字符串。

* max\_age

  integer

  默认值：`5`

  ***

  [预检请求](https://developer.mozilla.org/zh-CN/docs/Glossary/Preflight_request)结果可以缓存的最大时间（以秒为单位）。如果时间在此限制内，浏览器将检查缓存的结果。要禁用缓存，请将 `max_age` 设置为 `-1`。

  请注意，允许的最大值取决于浏览器。有关更多详细信息，请参阅 [`Access-Control-Max-Age`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Access-Control-Max-Age#指令)。

* allow\_credential

  boolean

  默认值：`false`

  ***

  如果为 true，则允许请求包含凭据，例如 cookie。根据 CORS 规范，当 `allow_credential` 设置为 true 时，不能将 `*` 用于其他 CORS 属性。

  要允许所有来源，请将该字段设置为 `**`。这可能会允许敏感的用户数据（如身份认证 Token 或 cookie）暴露给恶意行为者。

* allow\_origins\_by\_regex

  array\[string]

  ***

  用于匹配允许 CORS 的来源的正则表达式。配置后，将使用这些正则表达式匹配来源，取代通过 `allow_origins` 进行的字面匹配。

  如果同时配置了 `allow_origins_by_metadata`，则优先评估元数据中命名的来源。仅当 `allow_origins` 显式设置为 `*` 以外的值时，才回退到正则表达式匹配。

  例如，`['.*\.test.com$']` 可以匹配 `test.com` 的所有子域。

* allow\_origins\_by\_metadata

  array\[string]

  ***

  引用插件元数据中设置的 `allow_origins` 来启用 CORS 的来源。例如，如果在插件元数据中设置了 `allow_origins: {'EXAMPLE': 'https://example.com'}`，则可以使用 `['EXAMPLE']` 来允许来源 `https://example.com` 的 CORS。

  优先于本地来源设置评估元数据中命名的来源。如果均不匹配，仅当 `allow_origins` 显式设置为 `*` 以外的值时，才会尝试本地字面匹配或正则表达式匹配。

* timing\_allow\_origins

  string

  ***

  允许访问资源计时信息的来源，用逗号分隔的字符串。有关更多详细信息，请参阅 [`Timing-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin)。

* timing\_allow\_origins\_by\_regex

  array\[string]

  ***

  用于匹配允许访问资源计时信息的来源的正则表达式。配置后，仅允许匹配正则表达式的域，并且 `timing_allow_origins` 中的任何配置都将被忽略。

  例如，`['.*\.test.com']` 可以匹配 `test.com` 的所有子域。

## 插件元数据[​](#插件元数据 "插件元数据的直接链接")

* allow\_origins

  object

  ***

  允许 CORS 的命名来源映射，其中每个键都是由 `allow_origins_by_metadata` 引用的标识符，每个值都是对应的来源字符串。

  例如，`{'EXAMPLE': 'https://example.com'}` 为来源 `https://example.com` 定义了键 `EXAMPLE`。

  如果 `allow_credential` 设置为 `true`，可以将映射值设置为 `**`，以强制允许所有来源的 CORS，但身份认证 Token 或 Cookie 等敏感数据可能会暴露给恶意网站。
