koa-router 迁移到 @koa/router - Koa 路由中间件迁移指南

一、为什么要迁移？

随着 Koa 及其生态的更新，原来由开源社区维护的第三方路由中间件 koa-router 已经停止维护，不再进行漏洞修复、功能迭代或 TS 类型优化。官方推荐采用 @koa/router，这是由 Koa 核心团队维护的路由器，也是 Koa 未来生态的主力。

迁移动因总结

• 维护活跃：官方持续更新，安全性保障更高
• API 基本一致：低风险无痛升级
• 更优 TypeScript 支持：开发效率和代码质量提升
• 更高性能：路由查找优化、路径参数解析更快
• 生态主线：兼容最新 Koa 及主流社区工具链

二、迁移后的好处

三、可能的风险或注意点

• 包名变更：全部引入路径需修改为 @koa/router
• 类型兼容性：TS 项目需删除旧的 @types/koa-router，避免类型冲突
• Koa 版本要求：需 Koa v2+；Koa v1 项目需先升级框架
• 少量私有 API 或 Monkey Patch 场景可能需要微调
• 极少数底层类型或方法的参数命名可能有差异

四、迁移步骤

Step 1. 卸载老版本依赖

npm uninstall koa-router @types/koa-router
# 或
yarn remove koa-router @types/koa-router

Step 2. 安装新包

npm install @koa/router
# 或
yarn add @koa/router

Step 3. 全局替换 import/require 路径

// 旧写法（需替换）
import Router from 'koa-router'

// 新写法
import Router from '@koa/router'

Step 4. 类型声明自检与清理

删除与 koa-router 相关的自定义类型扩展，按需对齐 @koa/router 的新类型定义。如果扩展了 router context，请根据新版支持的泛型参数完善类型。

// 示例：自定义 ctx.state 类型
import Router from '@koa/router'

interface ICustomState {
	userId: string
}

const router = new Router<{}, ICustomState>()

Step 5. 跑测试、手动验证

• 执行自动化测试，确保业务功能未因路由升级受影响
• 若有 CI/CD，上线前回归集成测试

Step 6. 深度清理

• 检查 package.json、全局声明和脚手架配置，避免遗留 koa-router 相关配置项

五、常见迁移问题与解决建议

• 迁移后项目无法启动：检查 Koa 版本是否 >= 2.x，依赖是否全部升级
• TS 编译报错：确认是否已卸载 @types/koa-router，并对齐新的类型定义
• 路由参数类型推断错误：参考新版泛型接口定义，完善 context 泛型
• 存在自定义 hack 或私有 API 依赖：查阅 @koa/router 文档，尽量依赖公开 API，必要时调整写法

六、升级总结

• 迁移到 @koa/router 是官方社区的强烈建议
• 性能、安全与开发体验全面提升，兼容性风险低
• 注意 TS 类型兼容性和 Koa 版本要求
• 新项目直接使用 @koa/router，存量项目尽早迁移，保持技术栈健康