Ktor返回文件流触发io.netty WriteTimeoutException异常如何解决？

根因分析 #

这个异常是Ktor底层依赖的Netty框架触发的写超时：Netty默认配置了写入操作的超时时间，如果客户端网络慢，服务端写出的数据一直塞在Socket缓冲区没法发送到客户端，超过超时时间就会抛出WriteTimeoutException，最终触发协程任务取消。

解决方案 #

1. 调整Netty写超时配置 #

你可以直接修改Ktor服务端的写超时参数，根据你的业务场景适当延长超时时间，或者极端场景下禁用写超时：
如果用配置文件（application.conf），添加配置：

ktor {
    deployment {
        // 单位是毫秒，默认是10000（10秒），这里改成60秒，可按需调整
        writeTimeout = 60000
        // 如果你确定不需要写超时保护，设为0即可禁用
        // writeTimeout = 0
    }
}

如果是代码中配置服务端：

embeddedServer(Netty, port = 8080, configure = {
    responseWriteTimeoutSeconds = 60 // 单位秒，设为0禁用超时
}) {
    // 你的路由配置
}.start(wait = true)

注意：如果选择禁用写超时，需要做好服务端连接数和内存监控，避免大量慢客户端长时间占用连接导致资源耗尽。

2. 优化流处理逻辑 #

你现有代码有两个可以优化的点，能减少超时概率：

• 不要额外包装buffered()：respondOutputStream返回的输出流已经是Ktor封装的支持异步写的流，额外加缓冲会导致数据堆积在应用层缓冲区，没有及时刷给底层Netty，反而增加超时风险
• 不要吞掉取消异常：你现在的catch会捕获协程取消异常（CancellationException），这类异常是客户端断开或者超时触发的正常取消信号，吞掉之后会导致协程继续执行写操作，触发更多异常

修改后的代码示例：

suspend fun ApplicationCall.returnMultiFiles(files: List<StreamFile>) {
    log.debug("Returning Multiple Files: ${files.size}")
    val bufferSize = 16 * 1024

    response.headers.append(
        HttpHeaders.ContentDisposition,
        ContentDisposition.Attachment.withParameter(ContentDisposition.Parameters.FileName, "${UUID.randomUUID()}.zip").toString()
    )

    respondOutputStream(ContentType.parse("application/octet-stream")) {
        // 去掉额外的buffered包装，直接使用当前流
        ZipOutputStream(this).use { zipout ->
            files.forEach { record ->
                // 每次处理文件前先检查协程是否已经取消，避免无效执行
                currentCoroutineContext().ensureActive()
                try {
                    zipout.putNextEntry(ZipEntry(record.getZipEntry()))
                    log.debug("Adding: ${record.getZipEntry()}")
                    record.getInputStream().use { fileInput ->
                        fileInput.copyTo(zipout, bufferSize)
                    }
                    zipout.closeEntry()
                } catch (e: CancellationException) {
                    // 协程取消属于正常情况，直接抛出不捕获
                    throw e
                } catch (e: Exception) {
                    log.error("Failed to add ${record.getZipEntry()}", e)
                }
            }
        }
    }
}

3. 可选：分片写入增加让步机制 #

如果你的单文件体积非常大，可以把copyTo改成分片写入，每写一定数据就调用一次yield()，让协程有机会处理底层IO事件和取消信号，进一步降低超时概率：

// 替换原来的fileInput.copyTo(zipout, bufferSize)
val buffer = ByteArray(bufferSize)
var bytesRead: Int
while (fileInput.read(buffer).also { bytesRead = it } != -1) {
    zipout.write(buffer, 0, bytesRead)
    yield() // 每写一片就让渡协程，处理底层IO
}

可选：配置Content-Length头（提前知道包大小的场景） #

如果你的文件是固定的，可以提前计算出最终zip包的总大小，添加Content-Length响应头，能减少部分客户端的兼容性问题，也能让Netty更好的调度写入操作：

// 提前计算好zip大小
val totalSize = calculateZipSize(files) 
call.response.headers.append(HttpHeaders.ContentLength, totalSize.toString())

动态生成zip的场景下这个实现成本比较高，非必须。

内容的提问来源于stack exchange，提问作者ademarizu