将 Express 应用迁移到 Hono 的实用建议

如果你正在维护一个 Express API，并考虑迁移到 Hono，首先需要明白的是：这并不是一次简单的查找替换式迁移。Express 构建于 Node 的 http 模块及其自有的 req/res 对象之上，而 Hono 则建立在 Fetch API 和 Web 标准之上。这一根本差异影响着一切：路由、中间件、请求处理以及响应。

在开始之前，你需要了解以下内容。

先理解架构层面的差异

Express 封装了 Node 的 IncomingMessage 与 ServerResponse，因此每一个 req 和 res 对象都是 Node 专有的。相比之下，Hono 使用标准的 Request 和 Response 对象——与你在浏览器或 Cloudflare Worker 中使用的对象完全一致。

当在 Node.js 上运行 Hono 时，需要使用 @hono/node-server 适配器来弥合差异。但处理函数本身保持运行时无关性。

// Express
app.get('/users/:id', async (req, res) => {
  const user = await db.findById(req.params.id)
  res.json(user)
})

// Hono
app.get('/users/:id', async (c) => {
  const user = await db.findById(c.req.param('id'))
  return c.json(user)
})

形态相似，但 c（上下文对象）取代了 req 和 res。你返回的是一个 Response，而不是调用 res 上的方法。

将 Node.js API 迁移到 Hono：从无状态路由入手

将 Express 应用迁移到 Hono 时，最稳妥的起点是无状态的、仅返回 JSON 的路由——不涉及文件系统访问、不依赖 Node 专有的流，也不使用会话中间件。这类路由可以干净利落地完成转换。

而依赖 Node 专有 API（如 req.socket、res.locals、res.sendFile）的路由则需要更多考量。在着手全面迁移之前，先将这些路由隔离出来，搞清楚自己面对的是什么。

Hono 中间件迁移：不要想当然地认为兼容

Express 中间件遵循 (req, res, next) 的模式。Hono 中间件则使用 (c, next)，通常调用 await next()。两者并不可以互换。

// Express 中间件
app.use((req, res, next) => {
  req.startTime = Date.now()
  next()
})

// Hono 中的等效写法
app.use(async (c, next) => {
  c.set('startTime', Date.now())
  await next()
})

对于常用的包，Hono 提供了官方对应的实现：

建议主动重写中间件，而不是试图去包装 Express 中间件——这种抽象层很少能完美适配。

请求体与响应处理

在 Express 5 中，请求体解析仍然基于中间件。而在 Hono 中，你直接在处理函数中解析请求体：

// Hono 请求体解析
app.post('/items', async (c) => {
  const body = await c.req.json()
  return c.json({ received: body }, 201)
})

响应始终是被返回的，而不是被修改的。这里没有 res.status(201).json(...)——你需要将状态码作为第二个参数传给 c.json()。

错误处理

Express 使用四参数的错误处理函数 (err, req, res, next)。Hono 则使用 app.onError：

app.onError((err, c) => {
  console.error(err)
  return c.json({ error: 'Internal Server Error' }, 500)
})

渐进式迁移，而非一次性全部重写

完全重写极少能顺利推进。更好的方式是：

1. 一次只迁移一组隔离的路由。
2. 在过渡期内让 Hono 与 Express 并行运行。
3. 显式重写中间件——不要包装它。
4. 将 Node 专有的依赖（如文件处理、遗留的认证逻辑）留到最后处理。

结语

一旦你接受了 Express 与 Hono 建立在不同基础之上的事实，将 Express 应用迁移到 Hono 其实并不复杂。其路由语法足够熟悉，大多数路由几分钟内就能完成转换。真正的工作量在于中间件，以及任何直接接触 Node 专有 API 的部分。审慎地处理这些环节，迁移就会变得可控。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.