Skip to content
Server Plugin

CORS

必要相依性:io.ktor:ktor-server-cors

程式碼範例: cors

原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✅

如果你的伺服器需要處理跨來源請求 (cross-origin requests), 則需要安裝並設定 CORS Ktor 外掛程式。此外掛程式允許你設定允許的主機、HTTP 方法、用戶端設定的標頭等。

新增相依性 ​

若要使用 CORS,請將 ktor-server-cors 構件新增至你的建置指令碼:

kotlin
implementation(ktorLibs.server.cors)
上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.cors
上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 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 預檢請求 (preflight request)。

設定 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-")
}

請注意,對於非簡單內容類型 (non-simple content types),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 進一步了解其他設定選項。