Hono 适配器

@mastra/hono 包提供了一个服务器适配器，用于通过 Hono 运行 Mastra。有关通用适配器概念（构造函数选项、初始化流程等），请参阅 Server 适配器。

安装

安装 Hono 适配器和 Hono 框架：

npm

npm install @mastra/hono@latest hono

pnpm

pnpm add @mastra/hono@latest hono

Yarn

yarn add @mastra/hono@latest hono

Bun

bun add @mastra/hono@latest hono

使用示例

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

await server.init()

export default app

构造函数参数

app:

Hono

Hono 应用实例

mastra:

Mastra

Mastra 实例

prefix?:

string

= ''

路由路径前缀（例如：/api/v2）

openapiPath?:

string

= ''

提供 OpenAPI 规范的路径（例如：/openapi.json）

bodyLimitOptions?:

{ maxSize: number, onError: (err) => unknown }

请求正文大小限制

streamOptions?:

{ redact?: boolean }

= { redact: true }

流脱敏配置。设为 true 时，会从流中移除敏感数据。

customRouteAuthConfig?:

Map<string, boolean>

按路由覆盖认证配置。键为 METHOD:PATH（例如：GET:/api/health）。值为 false 时路由公开；为 true 时需要认证。

tools?:

Record<string, Tool>

服务器可用的 Tool

taskStore?:

InMemoryTaskStore

用于 A2A（Agent-to-Agent）操作的任务存储

mcpOptions?:

MCPOptions

MCP 传输选项。对于 Cloudflare Workers 或 Vercel Edge 等无状态环境，请设置 serverless: true。

添加自定义路由

直接向 Hono 应用添加路由：

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

// Before init - runs before Mastra middleware
app.get('/early-health', c => c.json({ status: 'ok' }))

await server.init()

// After init - has access to Mastra context
app.get('/custom', c => {
  const mastraInstance = c.get('mastra')
  return c.json({ agents: Object.keys(mastraInstance.listAgents()) })
})

提示

在 init() 前添加的路由会在没有 Mastra 上下文的情况下运行。请在 init() 后添加路由，以访问 Mastra 实例和请求上下文。

如需使用由 Mastra 管理的认证和 requiresAuth 等路由元数据，请优先使用 registerApiRoute()。对于直接挂载到 app 上的原始 Hono 路由，请使用 createAuthMiddleware()：

server.ts

import { Hono } from 'hono'
import { createAuthMiddleware, HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

await server.init()

app.get('/custom/protected', createAuthMiddleware({ mastra }), c => {
  const user = c.get('requestContext').get('user')
  return c.json({ user })
})

app.get('/custom/public', createAuthMiddleware({ mastra, requiresAuth: false }), c => {
  return c.json({ ok: true })
})

访问上下文

在 Hono 中间件和路由处理程序中，通过 c.get() 访问 Mastra 上下文：

app.get('/custom', async c => {
  const mastra = c.get('mastra')
  const requestContext = c.get('requestContext')
  const abortSignal = c.get('abortSignal')

  const agent = mastra.getAgent('myAgent')
  return c.json({ agent: agent.name })
})

可用的上下文键：

键	说明
mastra	Mastra 实例
requestContext	请求上下文映射
abortSignal	请求取消信号
tools	可用的 Tool
taskStore	用于 A2A 操作的任务存储
customRouteAuthConfig	按路由覆盖认证配置
user	已认证的用户（如果已配置认证）

添加中间件

在 init() 前或后添加 Hono 中间件：

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()

// Middleware before init
app.use('*', async (c, next) => {
  console.log(`${c.req.method} ${c.req.url}`)
  await next()
})

const server = new MastraServer({ app, mastra })
await server.init()

// Middleware after init has access to Mastra context
app.use('*', async (c, next) => {
  const mastra = c.get('mastra')
  await next()
})

手动初始化

如需自定义中间件顺序，请分别调用各个方法，而非调用 init()。详情请参阅手动初始化。

示例

• Hono 适配器：基础 Hono 服务器设置

相关内容

• Server 适配器：共享的适配器概念
• MastraServer 参考：完整 API 参考
• createRoute() 参考：创建类型安全的自定义路由