Koa
由 Express 原团队打造、以 async 洋葱中间件为核心的极简 Node.js Web 框架。
项目概述
Koa 用小巧的核心、统一的 Context 和可组合的 async 中间件为 Node.js Web 应用提供基础。它不内置路由、请求体解析等功能，适合按需构建 API、BFF 和自定义服务框架。
Koa 是由 Express 背后的团队设计的 Node.js Web 框架，目标是为 Web 应用和 API 提供更小、更具表达力且更可靠的基础。它围绕 async 函数组合中间件：请求沿注册顺序向下执行，在 await next() 返回后再反向执行，形成适合统一计时、错误处理和响应加工的“洋葱模型”。Koa 将 Node.js 的 request 与 response 封装进单个 Context，同时仍允许访问底层对象。核心刻意不捆绑路由、Body Parser、验证或认证，团队可按业务需要组装技术栈；Koa 3 还可通过 AsyncLocalStorage 暴露当前请求上下文。
主要特点
Koa 以精简核心和双向 async 中间件组合请求生命周期，为上层框架与定制后端保留充分空间。
Async 洋葱模型
中间件先按顺序执行下游逻辑，再在 await next() 返回后逆序执行上游逻辑，适合错误边界、计时、追踪和响应转换。
无捆绑的精简核心
核心不内置路由、Body Parser、认证或数据库，可只引入项目真正需要的模块，避免框架预设过多技术选择。
统一 Context
ctx 封装请求与响应并提供 status、body、type、query、cookies 等便捷 API，同时保留 ctx.req 与 ctx.res 访问底层 Node 对象。
内容协商与响应辅助
通过 ctx.accepts、ctx.is、ctx.type、ctx.body 等接口处理媒体类型、请求内容判断和常见响应，无需重复编写底层 Header 逻辑。
集中错误处理
最外层中间件可用 try/catch 捕获下游错误，应用还会触发 error 事件，便于统一响应、日志记录和异常上报。
请求状态容器
ctx.state 是在认证、路由和业务中间件之间传递用户、权限、追踪 ID 等请求级数据的推荐命名空间。
Cookie 与代理支持
提供普通和签名 Cookie API，并可按部署拓扑配置代理信任、客户端 IP 与安全连接判断。
Koa 3 请求上下文
启用 asyncLocalStorage 后可通过 app.currentContext 获取当前请求上下文，方便深层服务读取追踪或租户信息。
适用场景
适合希望掌控依赖与架构、需要优雅横切逻辑，或准备在薄 HTTP 基础上搭建内部平台的 Node.js 团队。
定制 REST API
按需组合 Router、Schema 验证、认证和数据层，构建依赖清晰且没有多余框架模块的业务接口。
BFF 与 API 网关
洋葱中间件适合集中实现身份校验、请求聚合、缓存、超时、日志和响应格式转换。
内部服务端框架
团队可在 Koa 薄核心上封装统一路由、错误、观测和依赖注入约定，形成面向自身业务的平台。
Webhook 与集成服务
小巧的请求模型适合接收第三方回调、验证签名，并将事件转交消息队列或内部服务。
流式响应与代理
ctx.body 可接收 Stream，结合底层 Node 能力可实现文件传输、上游代理和渐进式数据输出。
渐进式 Node.js 系统
不强制目录和数据层，便于将已有模块逐步接入统一的 HTTP Context 与中间件生命周期。
优点与注意事项
技术选型不仅要看能力，也要理解它带来的团队成本。
主要优点
Koa 擅长的地方
- 核心 API 小而稳定，理解 Context 与中间件组合后即可开始开发
- 洋葱模型让错误处理、耗时统计和响应后处理保持对称且集中
- 既提供便利的 Web API，又保留对 Node 原生请求响应对象的访问
- 路由、验证、日志和数据层均可按项目需求选择，不被单一方案绑定
- app.callback() 可直接交给 HTTP Server 或 Supertest，测试和嵌入都很方便
- Koa 3 的 AsyncLocalStorage 支持有助于传递请求级追踪和租户上下文
需要注意
采用前应考虑的问题
路由、Body Parser、验证、认证、日志和安全策略都需另选依赖，并由团队维护版本兼容与统一规范。
Koa 核心要求 Node.js 18+，但最新 @koa/router 要求 Node.js 20+；部署前应以完整依赖树的最高要求为准。
错误边界、认证、解析器和路由的注册顺序会改变行为；忘记 await next() 还会破坏上游恢复流程。
ctx.request.body、查询和路径参数都属于不可信输入，即使使用 TypeScript 也应通过 Zod 等 Schema 在边界验证。
直接操作原生 res 或设置 ctx.respond = false 容易破坏 Koa 的响应与错误处理约定，只应在明确的底层集成中使用。
proxy、proxyIpHeader、subdomainOffset 和签名密钥应与真实网络拓扑匹配，避免信任伪造 Header 或使用弱密钥。
Koa 不规定 Controller、Service 或模块结构；多人项目应尽早约定分层、依赖方向、错误格式和可观测性。
快速开始
使用 Koa 3、@koa/router、Zod 和 Supertest 创建带路由、验证、错误处理与测试的最小任务 API。
bashmkdir koa-tasks
cd koa-tasks
npm init -y
npm install koa @koa/router koa-bodyparser zod
npm install --save-dev typescript tsx @types/koa @types/koa-bodyparser @types/node supertest @types/supertesttypescriptimport Koa from "koa";
import Router from "@koa/router";
import bodyParser from "koa-bodyparser";
import { z, ZodError } from "zod";
const CreateTask = z.object({
title: z.string().trim().min(1).max(120),
});
export const app = new Koa();
const router = new Router({ prefix: "/api" });
app.use(async (ctx, next) => {
try {
await next();
} catch (error) {
if (error instanceof ZodError) {
ctx.status = 422;
ctx.body = {
error: "Validation failed",
issues: error.issues,
};
return;
}
ctx.app.emit("error", error, ctx);
ctx.status = 500;
ctx.body = { error: "Internal server error" };
}
});
app.use(async (ctx, next) => {
const startedAt = performance.now();
await next();
ctx.set("Server-Timing", `app;dur=${performance.now() - startedAt}`);
});
app.use(bodyParser({ jsonLimit: "100kb" }));
router.get("/health", (ctx) => {
ctx.body = { status: "ok" };
});
router.post("/tasks", (ctx) => {
const input = CreateTask.parse(ctx.request.body);
ctx.status = 201;
ctx.body = {
id: crypto.randomUUID(),
title: input.title,
completed: false,
};
});
app.use(router.routes());
app.use(router.allowedMethods());typescriptimport { app } from "./app.js";
const port = Number(process.env.PORT ?? 3000);
app.on("error", (error, ctx) => {
console.error({
error,
method: ctx?.method,
path: ctx?.path,
});
});
app.listen(port, "127.0.0.1", () => {
console.log(`Koa listening on http://127.0.0.1:${port}`);
});typescriptimport assert from "node:assert/strict";
import test from "node:test";
import request from "supertest";
import { app } from "../src/app.js";
test("creates a task", async () => {
const response = await request(app.callback())
.post("/api/tasks")
.send({ title: "学习 Koa" })
.expect(201);
assert.equal(response.body.title, "学习 Koa");
assert.equal(response.body.completed, false);
});typescriptimport Koa from "koa";
const app = new Koa({ asyncLocalStorage: true });
app.use(async (ctx, next) => {
ctx.state.requestId = crypto.randomUUID();
await next();
});
export function currentRequestId() {
return app.currentContext?.state.requestId;
}下一步：错误处理和请求计时应放在路由之前，并始终 await next()；最新 @koa/router 要求 Node.js 20+，即使 Koa 核心本身支持 Node.js 18+。
类似项目
这些框架同样面向 JavaScript/TypeScript 服务端开发，但在内置能力、性能目标和运行时选择上各有侧重。
Koa vs Express
Koa 与 Express 来自同一技术脉络，都保持较少架构约束。Koa 用 Context 和 async 洋葱模型提供更现代、对称的中间件控制流；Express 则内置 Router 与常用解析器，并拥有更庞大的兼容生态。
| 比较维度 | Koa | Express |
|---|---|---|
| 核心定位 | 面向自定义 Web 栈的极简异步基础 | 成熟、通用且生态广泛的极简 Web 框架 |
| 中间件模型 | await next() 后可逆序恢复的洋葱模型 | 按顺序调用 next 的线性 Middleware 堆栈 |
| 请求抽象 | 统一 ctx，封装 request 与 response | 独立 req 与 res，并扩展 Node 原生对象 |
| 路由 | 核心不内置，通常使用 @koa/router | 内置 app 路由 API 与 express.Router |
| 基础中间件 | 不捆绑 Body Parser、静态文件等能力 | 内置 JSON、URL-encoded 与静态资源中间件 |
| 错误处理 | 外层 async try/catch + app error 事件 | 四参数错误中间件，Express 5 支持 Promise 传播 |
| 生态与迁移 | 组件选择灵活，但需核对 Koa 专用适配 | Middleware、教程与历史系统兼容面更广 |
| 更适合 | 定制栈、对称横切逻辑和框架基础设施 | 快速接入成熟生态和维护既有 Node 系统 |
如果团队重视 async 中间件的对称控制流、希望以 Context 为中心并自行挑选每个组件，Koa 是简洁的基础；如果项目依赖大量现成 Middleware、需要内置 Router 与解析器，或团队更熟悉 req/res 模型，Express 通常更直接。两者都不会替团队定义大型应用架构，应把验证、安全、日志和模块边界纳入选型。
资料核验
版本、维护信息与本页采用的官方资料来源。
本次核验覆盖 Koa 的核心定位、主要能力、官方入口与开源许可。项目版本持续更新，具体补丁版本、兼容性和迁移要求请在采用前继续核对官方发布记录。
官方仓库未归档，核验时最近可见的代码活动日期为 2026 年 7 月 17 日。该状态表示项目近期仍有公开维护活动，不代表固定发布频率或长期支持承诺。