如何为Koa框架的ctx.state添加TypeScript类型定义

云原生阿岚

2026-7-15

解决方案：扩展Koa内置类型实现`ctx.state`类型约束

Koa的TypeScript类型系统支持通过模块扩展直接覆盖ctx.state的默认类型，无需在每个端点重复导入接口或使用类型断言，具体步骤如下：

1. 创建Koa类型声明文件

在项目src目录下新建类型声明文件（例如koa.d.ts），用于扩展Koa的内置类型定义。

2. 关联`ResObj`与`ContextState`

在声明文件中，通过TypeScript模块扩展语法，将Koa的ContextState接口与你的ResObj绑定：

// src/koa.d.ts
import { ResObj } from './path/to/your/res-obj-file'; // 替换为ResObj实际文件路径

declare module 'koa' {
  interface ContextState extends ResObj {}
}

如果需要让ctx.state包含ResObj的部分属性，或添加额外自定义字段，可调整为：

// 示例：基于ResObj扩展自定义字段
declare module 'koa' {
  interface ContextState extends Partial<ResObj> {
    // 这里可添加ResObj之外的额外状态字段
    currentUser?: { id: string; nickname: string };
  }
}

3. 配置TypeScript识别声明文件

确保tsconfig.json包含该声明文件的扫描路径：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src"]
  },
  "include": ["src/**/*"]
}

4. 验证类型效果

现在在中间件或路由中使用ctx.state时，TypeScript会自动识别其类型为ResObj（或扩展后的类型），自动补全属性并进行类型检查：

app.use(async (ctx) => {
  // 自动提示ResObj的所有属性，类型校验生效
  ctx.state.data = { items: [] };
  ctx.state.status = 200;
  ctx.state.tech.needRefresh = false;
});