跳至主要內容

Koa 轉接器

@mastra/koa 套件提供了一個 Server 轉接器，用於透過 Koa 執行 Mastra。有關通用轉接器概念（建構函式選項、初始化流程等），請參閱 Server Adapters。

安裝
「安裝」的直接連結

安裝 Koa 轉接器和 Koa 框架：

npm install @mastra/koa@latest koa koa-bodyparser

使用範例
「使用範例」的直接連結

server.ts
import Koa from 'koa'
import bodyParser from 'koa-bodyparser'
import { MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
app.use(bodyParser())

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

await server.init()

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000')
})

建構函式參數
「建構函式參數」的直接連結

app:

Koa
Koa app 執行個體

mastra:

Mastra
Mastra 執行個體

prefix?:

string
= ''
路由路徑前綴（例如，/api/v2）

openapiPath?:

string
= ''
提供 OpenAPI 規格的路徑（例如，/openapi.json）

bodyLimitOptions?:

BodyLimitOptions
請求請求主體大小限制

streamOptions?:

StreamOptions
= { redact: true }
串流遮罩設定。為 true（預設值）時，會在將串流 chunk 傳送給使用者端之前，從中刪除敏感資料（系統 prompt、Tool 定義、API 金鑰）。

customRouteAuthConfig?:

Map<string, boolean>
依路由覆寫身分驗證。鍵為 METHOD:PATH（例如，GET:/api/health）。值為 false 時路由公開，值為 true 時需要身分驗證。

tools?:

ToolsInput
Server 可用的 Tool

taskStore?:

InMemoryTaskStore
用於 A2A（Agent-to-Agent）操作的任務儲存

mcpOptions?:

MCPOptions
MCP 傳輸選項。對於 Cloudflare Workers 或 Vercel Edge 等無狀態環境，請設定 serverless: true。

錯誤處理
「錯誤處理」的直接連結

Koa 轉接器會沿 Koa 的 middleware 鏈向上傳播路由處理常式中的錯誤，並遵循 Koa 的標準錯誤處理模式。這意味著可以使用常規 Koa 錯誤處理 middleware：

server.ts
const app = new Koa()
app.use(bodyParser())

// Your error middleware catches errors from Mastra route handlers
app.use(async (ctx, next) => {
  try {
    await next()
  } catch (err) {
    ctx.status = err.status || 500
    ctx.body = { error: err.message }
    // Log, report to Sentry, etc.
  }
})

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

同樣支援 server.onError hook。設定後，它會在錯誤傳播至 middleware 之前呼叫，且會直接使用其回應：

src/mastra/index.ts
const mastra = new Mastra({
  server: {
    onError: (err, c) => {
      console.error('Unhandled error:', err)
      return c.json({ error: err.message }, 500)
    },
  },
})

使用 init() 時，還會註冊全域錯誤處理 middleware 作為安全網。到達此 middleware 的錯誤會遵循標準 Koa 約定，透過 ctx.app.emit('error', err, ctx) 發出。

保護原始路由
「保護原始路由」的直接連結

若要使用 Mastra 管理的身分驗證和 requiresAuth 等路由中繼資料，請優先使用 registerApiRoute()。對於直接掛載在 app 上的原始 Koa 路由，請使用 createAuthMiddleware()：

server.ts
import Koa from 'koa'
import { createAuthMiddleware, MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
const server = new MastraServer({ app, mastra })

await server.init()

app.use(createAuthMiddleware({ mastra }))
app.use(async ctx => {
  if (ctx.path !== '/custom/protected') return

  const user = ctx.state.requestContext.get('user')
  ctx.body = { user }
})

手動初始化
「手動初始化」的直接連結

如需自訂 middleware 順序，請分別呼叫每個方法，而不是呼叫 init()。詳見手動初始化。

範例
「範例」的直接連結

On this page