xml
<topic xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
title="程式碼中的組態"
id="server-configuration-code" help-id="Configuration-code;server-configuration-in-code">
<show-structure for="chapter"/>
<link-summary>
瞭解如何在程式碼中組態各種伺服器參數。
</link-summary>
<p>
Ktor 允許您直接在程式碼中組態各種伺服器參數，包括主機位址、埠、<Links href="/ktor/server-modules" summary="Modules allow you to structure your application by grouping routes.">伺服器模組</Links>等等。組態方法取決於您設定伺服器的方式——使用 <Links href="/ktor/server-create-and-configure" summary="Learn how to create a server depending on your application deployment needs.">embeddedServer 或 EngineMain</Links>。
</p>
<p>
使用 <code>embeddedServer</code>，您可以透過直接將所需參數傳遞給函式來組態伺服器。
<a href="https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/embedded-server.html">
embeddedServer
</a>
函式接受不同的參數來組態伺服器，包括<Links href="/ktor/server-engines" summary="Learn about engines that process network requests.">伺服器引擎</Links>、伺服器監聽的主機和埠，以及其他組態。
</p>
<p>
在本節中，我們將探討幾個執行 <code>embeddedServer</code> 的不同範例，
說明如何組態伺服器以發揮其優勢。
</p>
<chapter title="基本組態" id="embedded-basic">
<p>
以下程式碼片段顯示了使用 Netty 引擎和 <code>8080</code> 埠的基本伺服器設定。
</p>
<code-block lang="kotlin" code="import io.ktor.server.response.* import io.ktor.server.routing.* import io.ktor.server.engine.* import io.ktor.server.netty.* fun main(args: Array<String>) { embeddedServer(Netty, port = 8080) { routing { get("/") { call.respondText("Hello, world!") } } }.start(wait = true) }"/>
<p>
請注意，您可以將 <code>port</code> 參數設定為 <code>0</code> 以在隨機埠上執行伺服器。
<code>embeddedServer</code> 函式會返回一個引擎實例，因此您可以透過使用
<a href="https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/-application-engine/resolved-connectors.html">
ApplicationEngine.resolvedConnectors
</a>
函式在程式碼中取得埠值。
</p>
</chapter>
<chapter title="引擎組態" id="embedded-engine">
<snippet id="embedded-engine-configuration">
<p>
<code>embeddedServer</code> 函式允許您使用 <code>configure</code> 參數傳遞引擎特定選項。此參數包含所有引擎通用的選項，並由
<a href="https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/-application-engine/-configuration/index.html">
ApplicationEngine.Configuration
</a>
類別公開。
</p>
<p>
以下範例展示了如何使用 <code>Netty</code> 引擎組態伺服器。在 <code>configure</code> 區塊中，我們定義了一個 <code>connector</code> 以指定主機和埠，並自訂各種伺服器參數：
</p>
<code-block lang="kotlin" code="import io.ktor.server.response.* import io.ktor.server.routing.* import io.ktor.server.engine.* import io.ktor.server.netty.* fun main(args: Array<String>) { embeddedServer(Netty, configure = { connectors.add(EngineConnectorBuilder().apply { host = "127.0.0.1" port = 8080 }) connectionGroupSize = 2 workerGroupSize = 5 callGroupSize = 10 shutdownGracePeriod = 2000 shutdownTimeout = 3000 }) { routing { get("/") { call.respondText("Hello, world!") } } }.start(wait = true) }"/>
<p>
<code>connectors.add()</code> 方法定義了一個帶有指定主機 (<code>127.0.0.1</code>)
和埠 (<code>8080</code>) 的連接器。
</p>
<p>除了這些選項之外，您還可以組態其他引擎特定的屬性。</p>
<chapter title="Netty" id="netty-code">
<p>
Netty 特定選項由
<a href="https://api.ktor.io/ktor-server/ktor-server-netty/io.ktor.server.netty/-netty-application-engine/-configuration/index.html">
NettyApplicationEngine.Configuration
</a>
類別公開。
</p>
<code-block lang="kotlin" code=" import io.ktor.server.engine.* import io.ktor.server.netty.* fun main() { embeddedServer(Netty, configure = { requestQueueLimit = 16 shareWorkGroup = false configureBootstrap = { // ... } responseWriteTimeoutSeconds = 10 }) { // ... }.start(true) }"/>
</chapter>
<chapter title="Jetty" id="jetty-code">
<p>
Jetty 特定選項由
<a href="https://api.ktor.io/ktor-server/ktor-server-jetty-jakarta/io.ktor.server.jetty.jakarta/-jetty-application-engine-base/-configuration/index.html">
JettyApplicationEngineBase.Configuration
</a>
類別公開。
</p>
<p>您可以在
<a href="https://api.ktor.io/ktor-server/ktor-server-jetty-jakarta/io.ktor.server.jetty.jakarta/-jetty-application-engine-base/-configuration/configure-server.html">
configureServer
</a>
區塊內部組態 Jetty 伺服器，該區塊提供對
<a href="https://www.eclipse.org/jetty/javadoc/jetty-11/org/eclipse/jetty/server/Server.html">Server</a>
實例的存取。
</p>
<p>
使用 <code>idleTimeout</code> 屬性指定連線在關閉之前可以閒置的時間。
</p>
<code-block lang="kotlin" code=" import io.ktor.server.engine.* import io.ktor.server.jetty.jakarta.* fun main() { embeddedServer(Jetty, configure = { configureServer = { // this: Server -&gt; // ... } idleTimeout = 30.seconds }) { // ... }.start(true) }"/>
</chapter>
<chapter title="CIO" id="cio-code">
<p>CIO 特定選項由
<a href="https://api.ktor.io/ktor-server/ktor-server-cio/io.ktor.server.cio/-c-i-o-application-engine/-configuration/index.html">
CIOApplicationEngine.Configuration
</a>
類別公開。
</p>
<code-block lang="kotlin" code=" import io.ktor.server.engine.* import io.ktor.server.cio.* fun main() { embeddedServer(CIO, configure = { connectionIdleTimeoutSeconds = 45 }) { // ... }.start(true) }"/>
</chapter>
<chapter title="Tomcat" id="tomcat-code">
<p>如果您使用 Tomcat 作為引擎，您可以使用
<a href="https://api.ktor.io/ktor-server/ktor-server-tomcat-jakarta/io.ktor.server.tomcat.jakarta/-tomcat-application-engine/-configuration/configure-tomcat.html">
configureTomcat
</a>
屬性組態它，該屬性提供對
<a href="https://tomcat.apache.org/tomcat-10.1-doc/api/org/apache/catalina/startup/Tomcat.html">Tomcat</a>
實例的存取。
</p>
<code-block lang="kotlin" code=" import io.ktor.server.engine.* import io.ktor.server.tomcat.jakarta.* fun main() { embeddedServer(Tomcat, configure = { configureTomcat = { // this: Tomcat -&gt; // ... } }) { // ... }.start(true) }"/>
</chapter>
</snippet>
</chapter>
<chapter title="自訂環境" id="embedded-custom">
<p>
以下範例展示了如何使用
<a href="https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/-application-engine/-configuration/index.html">
ApplicationEngine.Configuration
</a>
類別表示的自訂組態來執行具有多個連接器端點的伺服器。
</p>
<code-block lang="kotlin" code="import io.ktor.server.application.* import io.ktor.server.response.* import io.ktor.server.routing.* import io.ktor.server.engine.* import io.ktor.server.netty.* fun main() { val appProperties = serverConfig { module { module() } } embeddedServer(Netty, appProperties) { envConfig() }.start(true) } fun ApplicationEngine.Configuration.envConfig() { connector { host = "0.0.0.0" port = 8080 } connector { host = "127.0.0.1" port = 9090 } }"/>
<p>
有關完整範例，請參閱
<a href="https://github.com/ktorio/ktor-documentation/tree/3.2.3/codeSnippets/snippets/embedded-server-multiple-connectors">
embedded-server-multiple-connectors
</a>。
</p>
<tip>
<p>
您也可以使用自訂環境來
<a href="#embedded-server">
提供 HTTPS 服務
</a>。
</p>
</tip>
</chapter>
<chapter id="command-line" title="命令列組態">
<p>
Ktor 允許您使用命令列引數動態組態 <code>embeddedServer</code>。這在需要於執行時指定埠、主機或逾時等組態的情況下特別有用。
</p>
<p>
為實現此目的，請使用
<a href="https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/-command-line-config.html">
CommandLineConfig
</a>
類別將命令列引數解析為組態物件，並將其傳遞到組態區塊中：
</p>
<code-block lang="kotlin" code="fun main(args: Array<String>) { embeddedServer( factory = Netty, configure = { val cliConfig = CommandLineConfig(args) takeFrom(cliConfig.engineConfig) loadCommonConfiguration(cliConfig.rootConfig.environment.config) } ) { routing { get("/") { call.respondText("Hello, world!") } } }.start(wait = true) }"/>
<p>
在此範例中，來自 <code>Application.Configuration</code> 的
<a href="https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/-application-engine/-configuration/take-from.html">
<code>takeFrom()</code>
</a>
函式用於覆寫引擎組態值，例如 <code>port</code> 和 <code>host</code>。
<a href="https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/load-common-configuration.html">
<code>loadCommonConfiguration()</code>
</a>
函式從根環境載入組態，例如逾時。
</p>
<p>
若要執行伺服器，請以下列方式指定引數：
</p>
<code-block lang="shell" code=" ./gradlew run --args="-port=8080""/>
<tip>
<p>
對於靜態組態，您可以使用組態檔或環境變數。
若要瞭解更多資訊，請參閱
<a href="#command-line">
檔案中的組態
</a>
。
</p>
</tip>
</chapter>