Skip to content
Server Plugin

CORS

必需依赖项:io.ktor:ktor-server-cors

代码示例: cors

原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✅

如果您的服务器需要处理跨源请求,则需要安装并配置 CORS Ktor 插件。此插件允许您配置允许的主机、HTTP 方法、客户端设置的标头等。

添加依赖项 ​

要使用 CORS,请将 ktor-server-cors 工件添加到您的构建脚本中:

kotlin
implementation(ktorLibs.server.cors)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.server.cors
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-cors-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

安装 CORS ​

要将 CORS 插件安装到您的应用程序中,请将其传递给指定模块模块允许您通过对路由进行分组来构建应用程序结构。中的 install 函数。以下示例展示了如何安装 CORS:

  • 在 embeddedServer() 函数调用中。
  • 在 Application 类上显式定义的 module() 扩展函数中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(CORS)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
// ...
fun Application.module() {
    install(CORS)
    // ...
}

CORS 插件也可以安装到特定路由。如果您需要为不同的应用程序资源配置不同的 CORS 配置,这会非常有用。

如果将 CORS 插件安装到特定路由,您需要向该路由添加 options 处理程序。这样 Ktor 才能正确响应 CORS 预检请求。

配置 CORS ​

CORS 专属配置设置由 CORSConfig 类公开。让我们来看看如何配置这些设置。

概述 ​

假设您有一个侦听在 8080 端口上的服务器,其 /customer 路由响应 JSON 数据。以下代码段展示了在另一个端口上运行的客户端使用 Fetch API 发起请求,使该请求成为跨源请求的示例:

javascript
function saveCustomer() {
    fetch('http://0.0.0.0:8080/customer',
        {
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json'
            },
            method: "POST",
            body: JSON.stringify({id: 3, firstName: "Jet", lastName: "Brains"})
        })
        .then(response => response.text())
        .then(data => {
            console.log('Success:', data);
            alert(data);
        })
        .catch((error) => {
            console.error('Error:', error);
        });
}

为了在后端允许此类请求,您需要按如下方式配置 CORS 插件:

kotlin
install(CORS) {
    allowHost("0.0.0.0:8081")
    allowHeader(HttpHeaders.ContentType)
}

您可以在此处找到完整示例:cors。

主机 ​

要指定允许发起跨源请求的主机,请使用 allowHost 函数。除主机名外,您还可以指定端口号、子域列表或支持的 HTTP scheme。

kotlin
install(CORS) {
    allowHost("client-host")
    allowHost("client-host:8081")
    allowHost("client-host", subDomains = listOf("en", "de", "es"))
    allowHost("client-host", schemes = listOf("http", "https"))
}

要允许来自任意主机的跨源请求,请使用 anyHost 函数。

kotlin
install(CORS) {
    anyHost()
}

HTTP 方法 ​

默认情况下,CORS 插件允许 GET、POST 和 HEAD HTTP 方法。要添加其他方法,请使用 allowMethod 函数。

kotlin
install(CORS) {
    allowMethod(HttpMethod.Options)
    allowMethod(HttpMethod.Put)
    allowMethod(HttpMethod.Patch)
    allowMethod(HttpMethod.Delete)
}

允许的标头 ​

默认情况下,CORS 插件允许以下由 Access-Control-Allow-Headers 管理的客户端标头:

  • Accept
  • Accept-Language
  • Content-Language

要允许其他标头,请使用 allowHeader 函数。

kotlin
install(CORS) {
    allowHeader(HttpHeaders.ContentType)
    allowHeader(HttpHeaders.Authorization)
}

要允许自定义标头,请使用 allowHeaders 或 allowHeadersPrefixed 函数。例如,以下代码段展示了如何允许带有 custom- 前缀的标头。

kotlin
install(CORS) {
    allowHeadersPrefixed("custom-")
}

请注意,对于非简单内容类型,allowHeaders 或 allowHeadersPrefixed 需要将 allowNonSimpleContentTypes 属性设置为 true。

公开标头 ​

Access-Control-Expose-Headers 标头将指定的标头添加到浏览器中的 JavaScript 可以访问的允许列表中。 要配置此类标头,请使用 exposeHeader 函数。

kotlin
install(CORS) {
    // ...
    exposeHeader("X-My-Custom-Header")
    exposeHeader("X-Another-Custom-Header")
}

凭据 ​

默认情况下,浏览器不会在跨源请求中发送凭据信息(例如 Cookie 或身份验证信息)。要允许传递此类信息,请使用 allowCredentials 属性将 Access-Control-Allow-Credentials 响应标头设置为 true。

kotlin
install(CORS) {
    allowCredentials = true
}

其他设置 ​

CORS 插件还允许您指定其他与 CORS 相关的设置。例如,您可以使用 maxAgeInSeconds 来指定预检请求的响应在不发送另一个预检请求的情况下可以缓存多长时间。

kotlin
install(CORS) {
    maxAgeInSeconds = 3600
}

您可以参阅 CORSConfig 了解详情并查看其他配置选项。