> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# 伺服器適配器

伺服器適配器讓你使用自己的 HTTP 伺服器執行 Mastra，而非使用由 `mastra build` 產生的 Hono 伺服器。你可以更全面地控制伺服器設定，包括自訂中介軟件次序、身份驗證、日誌記錄及部署配置。你仍可將 Mastra 整合至任何 Node.js 應用程式，而毋須改變 Agent 或 Workflow 的執行方式。

> **注意:** 伺服器適配器會使用你傳入的 `mastra` 實例，並不會執行以檔案為基礎的探索。請在程式碼中將 Agent 註冊至該實例。如要使用以檔案為基礎的 Agent，請透過 `mastra dev` 或 `mastra build` 將 Mastra 作為獨立伺服器執行。

## 何時使用伺服器適配器

- 你想將 Mastra 的端點自動加入現有應用程式
- 你需要直接存取伺服器實例以進行自訂配置
- 你的團隊偏好使用其他伺服器框架，而非由 `mastra build` 建立的 Hono 伺服器。

> **提示:** 如果部署沒有自訂伺服器需求，請改用 `mastra build`。它會配置伺服器設定並註冊中介軟件，亦會根據你的項目配置套用部署設定。詳情請參閱[伺服器配置](https://mastra.zisheng.pro/zh-HK/docs/server/mastra-server)。
>
> 如要配合伺服器適配器使用 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)，請使用 [`mastra studio`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra) 只啟動 Studio UI。

## 可用的適配器

Mastra 目前提供以下官方伺服器適配器：

- [@mastra/express](https://mastra.zisheng.pro/zh-HK/reference/server/express-adapter)
- [@mastra/hono](https://mastra.zisheng.pro/zh-HK/reference/server/hono-adapter)
- [@mastra/fastify](https://mastra.zisheng.pro/zh-HK/reference/server/fastify-adapter)
- [@mastra/koa](https://mastra.zisheng.pro/zh-HK/reference/server/koa-adapter)
- [@mastra/nestjs](https://mastra.zisheng.pro/zh-HK/reference/server/nestjs-adapter)

你亦可自行建立適配器，詳情請參閱[自訂適配器](https://mastra.zisheng.pro/zh-HK/docs/server/custom-adapters)。

## 安裝

安裝你所選框架的適配器。

**Express**:

**npm**:

```bash
npm install @mastra/express@latest
```

**pnpm**:

```bash
pnpm add @mastra/express@latest
```

**Yarn**:

```bash
yarn add @mastra/express@latest
```

**Bun**:

```bash
bun add @mastra/express@latest
```

**Hono**:

```bash
npm install @mastra/express@latest
```

**Fastify**:

```bash
pnpm add @mastra/express@latest
```

**Koa**:

```bash
yarn add @mastra/express@latest
```

**NestJS**:

```bash
bun add @mastra/express@latest
```

**Tab 6**:

**npm**:

```bash
npm install @mastra/hono@latest
```

**pnpm**:

```bash
pnpm add @mastra/hono@latest
```

**Yarn**:

```bash
yarn add @mastra/hono@latest
```

**Bun**:

```bash
bun add @mastra/hono@latest
```

**Tab 7**:

```bash
npm install @mastra/hono@latest
```

**Tab 8**:

```bash
pnpm add @mastra/hono@latest
```

**Tab 9**:

```bash
yarn add @mastra/hono@latest
```

**Tab 10**:

```bash
bun add @mastra/hono@latest
```

**Tab 11**:

**npm**:

```bash
npm install @mastra/fastify@latest
```

**pnpm**:

```bash
pnpm add @mastra/fastify@latest
```

**Yarn**:

```bash
yarn add @mastra/fastify@latest
```

**Bun**:

```bash
bun add @mastra/fastify@latest
```

**Tab 12**:

```bash
npm install @mastra/fastify@latest
```

**Tab 13**:

```bash
pnpm add @mastra/fastify@latest
```

**Tab 14**:

```bash
yarn add @mastra/fastify@latest
```

**Tab 15**:

```bash
bun add @mastra/fastify@latest
```

**Tab 16**:

**npm**:

```bash
npm install @mastra/koa@latest
```

**pnpm**:

```bash
pnpm add @mastra/koa@latest
```

**Yarn**:

```bash
yarn add @mastra/koa@latest
```

**Bun**:

```bash
bun add @mastra/koa@latest
```

**Tab 17**:

```bash
npm install @mastra/koa@latest
```

**Tab 18**:

```bash
pnpm add @mastra/koa@latest
```

**Tab 19**:

```bash
yarn add @mastra/koa@latest
```

**Tab 20**:

```bash
bun add @mastra/koa@latest
```

**Tab 21**:

**npm**:

```bash
npm install @mastra/nestjs@latest
```

**pnpm**:

```bash
pnpm add @mastra/nestjs@latest
```

**Yarn**:

```bash
yarn add @mastra/nestjs@latest
```

**Bun**:

```bash
bun add @mastra/nestjs@latest
```

**Tab 22**:

```bash
npm install @mastra/nestjs@latest
```

**Tab 23**:

```bash
pnpm add @mastra/nestjs@latest
```

**Tab 24**:

```bash
yarn add @mastra/nestjs@latest
```

**Tab 25**:

```bash
bun add @mastra/nestjs@latest
```

## 配置

如常初始化你的應用程式，然後建立 `MastraServer`，並傳入 `app` 及主要 `mastra` 實例（後者來自 `src/mastra/index.ts`）。呼叫 `init()` 會自動註冊 Mastra 中介軟件及所有可用端點。你可以繼續如常加入自己的路由，不論在 `init()` 之前或之後加入，它們都會與 Mastra 的端點一同運作。

**Express**:

```typescript
import express from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
app.use(express.json())

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

await server.init()

app.listen(4111, () => {
  console.log('Server running on port 4111')
})
```

如需完整配置選項，請參閱 [Express 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/express-adapter)文件。

**Hono**:

```typescript
import { Hono } from 'hono'
import { serve } from '@hono/node-server'
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()

serve({ fetch: app.fetch, port: 4111 }, () => {
  console.log('Server running on port 4111')
})
```

如需完整配置選項，請參閱 [Hono 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/hono-adapter)文件。

**Fastify**:

```typescript
import Fastify from 'fastify'
import { MastraServer } from '@mastra/fastify'
import { mastra } from './mastra'

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

await server.init()

app.get('/health', async request => {
  const mastraInstance = request.mastra
  const agents = Object.keys(mastraInstance.listAgents())
  return { status: 'ok', agents }
})

const port = 4111

app.listen({ port }, () => {
  console.log(`Server running on http://localhost:${port}`)
  console.log(`Try: curl http://localhost:${port}/api/agents`)
})
```

如需完整配置選項，請參閱 [Fastify 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/fastify-adapter)文件。

**Koa**:

```typescript
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()) // Required for body parsing

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

await server.init()

app.use(async (ctx, next) => {
  if (ctx.path === '/health' && ctx.method === 'GET') {
    const mastraInstance = ctx.state.mastra
    const agents = Object.keys(mastraInstance.listAgents())
    ctx.body = { status: 'ok', agents }
    return
  }
  await next()
})

const port = 4111

app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`)
  console.log(`Try: curl http://localhost:${port}/api/agents`)
})
```

如需完整配置選項，請參閱 [Koa 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/koa-adapter)文件。

**NestJS**:

```typescript
import { Module } from '@nestjs/common'
import { MastraModule } from '@mastra/nestjs'
import { mastra } from './mastra'

@Module({
  imports: [
    MastraModule.register({
      mastra,
    }),
  ],
})
export class AppModule {}
```

```typescript
import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  await app.listen(3000)
}

bootstrap()
```

如需完整配置選項，請參閱 [NestJS 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/nestjs-adapter)文件。

## 初始化流程

呼叫 `init()` 會依次執行三個步驟。了解此流程，有助你在特定位置插入自己的中介軟件。

1. `registerContextMiddleware()`：將 Mastra 實例、請求內容、Tool 及中止訊號附加至每個請求，讓所有後續中介軟件及路由處理程式都可使用 Mastra。
2. `registerAuthMiddleware()`：在初始化期間執行適配器的身份驗證掛鈎。當 Mastra 註冊內置路由及 `registerApiRoute()` 路由時，官方適配器會在路由內強制執行身份驗證。因此，原生框架路由如需 Mastra 身份驗證，應使用適配器匯出的 `createAuthMiddleware()` 輔助函數。
3. `registerRoutes()`：註冊 Agent、Workflow 及其他功能的所有 Mastra API 路由。如果已配置 MCP 伺服器，亦會註冊 MCP 路由。

### 手動初始化

如要自訂中介軟件次序，請分別呼叫每個方法，而非使用 `init()`。如需在設定 Mastra 內容前執行中介軟件，或在各初始化步驟之間插入邏輯，這種方式便很實用。

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

// Your middleware first
app.use(loggingMiddleware);

server.registerContextMiddleware();

// Middleware that needs Mastra context
app.use(customMiddleware);

await server.registerRoutes();

// Routes after Mastra
app.get('/health', ...);
```

> **提示:** 如需在 Mastra 內容可用前執行中介軟件，或在內容與身份驗證步驟之間插入中介軟件，請使用手動初始化。

## 加入自訂路由

你可以在應用程式中加入自己的路由，與 Mastra 路由並用。

- 在 `init()` **之前**加入的路由無法使用 Mastra 內容。
- 在 `init()` **之後**加入的路由可存取 Mastra 內容（Mastra 實例、請求內容、已驗證身份的用戶等）。
- 如需由 Mastra 管理身份驗證及 `requiresAuth` 等路由 metadata，建議使用 `registerApiRoute()`。
- 如果直接在框架應用程式掛載路由，而這些路由需要 Mastra 身份驗證，請使用適配器匯出的 `createAuthMiddleware()` 輔助函數。

如需更多資訊，請參閱 Express 及 Hono 的「加入自訂路由」：[Express](https://mastra.zisheng.pro/zh-HK/reference/server/express-adapter)和 [Hono](https://mastra.zisheng.pro/zh-HK/reference/server/hono-adapter)。

## 路由前綴

Mastra 路由預設註冊於 `/api/agents`、`/api/workflows` 等路徑。使用 `prefix` 選項即可更改。這適用於 API 版本控制，或整合至本身已有 `/api` 路由的現有應用程式。

```typescript
const server = new MastraServer({
  app,
  mastra,
  prefix: '/api/v2',
})
```

使用此前綴後，Mastra 路由會變為 `/api/v2/agents`、`/api/v2/workflows` 等路徑。你直接加入應用程式的自訂路由不受此前綴影響。

## OpenAPI 規格

Mastra 可為所有已註冊路由產生 OpenAPI 規格，適用於文件、用戶端產生或與 API Tool 整合。設定 `openapiPath` 選項即可啟用：

```typescript
const server = new MastraServer({
  app,
  mastra,
  openapiPath: '/openapi.json',
})
```

此規格會根據每個路由所定義的 Zod schema 產生，並於指定路徑提供。當中包括所有 Mastra 路由，以及使用 `createRoute()` 建立的任何自訂路由。

## 串流資料遮蔽

透過 HTTP 串流傳送 Agent 回應時，HTTP 串流層會先遮蔽串流區塊中的敏感資料，然後才傳送至用戶端。這可防止意外洩露以下資料：

- 系統提示及 Agent 指示
- Tool 定義及其參數
- 請求內容中的 API 金鑰及其他憑證
- 內部配置資料

遮蔽處理會在 HTTP 邊界進行，因此 `onStepFinish` 等內部回呼仍可存取完整請求資料，以供偵錯及可觀測性用途。

遮蔽功能預設啟用。請透過 `streamOptions` 配置此行為。只有內部服務或偵錯情境需要存取串流回應中的完整請求資料時，才應設定 `redact: false`。

```typescript
const server = new MastraServer({
  app,
  mastra,
  streamOptions: {
    redact: true, // Default
  },
})
```

如需完整配置選項，請參閱 [MastraServer](https://mastra.zisheng.pro/zh-HK/reference/server/mastra-server)。

## 覆寫個別路由的身份驗證設定

在 Mastra 實例配置身份驗證後，所有路由預設都需要身份驗證。有時你需要例外情況，例如公開的健康狀態檢查端點或 webhook 接收器；又或需要更嚴格控制的管理員路由。

使用 `customRouteAuthConfig` 覆寫特定路由的身份驗證行為。key 採用 `METHOD:PATH` 格式，其中 method 為 `GET`、`POST`、`PUT`、`DELETE` 或 `ALL`。路徑支援萬用字元（`*`），可配對多個路由。將值設為 `false` 會公開該路由，而 `true` 則要求身份驗證。

```typescript
const server = new MastraServer({
  app,
  mastra,
  customRouteAuthConfig: new Map([
    // Public health check
    ['GET:/api/health', false],
    // Public API spec
    ['GET:/api/openapi.json', false],
    // Public webhook endpoints
    ['POST:/api/webhooks/*', false],
    // Require auth even if globally disabled
    ['POST:/api/admin/reset', true],
    // Protect all methods on internal routes
    ['ALL:/api/internal/*', true],
  ]),
})
```

如需完整配置選項，請參閱 [MastraServer](https://mastra.zisheng.pro/zh-HK/reference/server/mastra-server)。

## 存取應用程式

建立適配器後，你可能仍需存取底層框架應用程式。將它傳入平台的 `serve` 函數，或從另一個模組加入路由時，這會很實用。

```typescript
// Via the MastraServer instance
const app = server.getApp()

// Via the Mastra instance (available after adapter construction)
const app = mastra.getServerApp()
```

兩種方法都會傳回同一個應用程式實例。請根據目前作用域，選用較方便的方法。

## 伺服器配置與適配器選項

使用伺服器適配器時，配置來自兩處：Mastra `server` 配置（傳入 `Mastra` constructor）及適配器 constructor 選項。了解各選項的來源，有助避免設定看似沒有生效時產生混淆。

### 適配器會使用的設定

適配器會從 `mastra.getServer()` 讀取以下設定：

| 選項              | 說明                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `auth`          | 身份驗證配置，由 `registerAuthMiddleware()` 使用。                                                                   |
| `bodySizeLimit` | 預設內容大小上限（以 byte 為單位）。可透過 `bodyLimitOptions` 針對個別適配器覆寫。                                                    |
| `onError`       | 路由處理程式發生未處理錯誤時呼叫的自訂錯誤處理程式。請參閱 [server.onError](https://mastra.zisheng.pro/zh-HK/reference/configuration)。 |

### 僅限適配器 constructor

以下選項會直接傳入適配器 constructor，而不會從 Mastra 配置讀取：

| 選項                      | 說明                                      |
| ----------------------- | --------------------------------------- |
| `prefix`                | 路由路徑前綴                                  |
| `openapiPath`           | OpenAPI 規格端點                            |
| `bodyLimitOptions`      | 附有自訂錯誤處理程式的內容大小上限                       |
| `streamOptions`         | 串流遮蔽設定                                  |
| `customRouteAuthConfig` | 個別路由的身份驗證覆寫設定                           |
| `mcpOptions`            | MCP 傳輸選項（例如，無狀態環境使用 `serverless: true`） |

### 適配器不會使用的設定

以下 `server` 配置選項只供 `mastra build` 使用，直接使用適配器時不會產生任何作用：

| 選項             | 使用者                                      |
| -------------- | ---------------------------------------- |
| `port`, `host` | `mastra dev`, `mastra build`             |
| `cors`         | `mastra build` 會加入 CORS 中介軟件             |
| `timeout`      | `mastra build`                           |
| `apiRoutes`    | `registerApiRoute()`，供 `mastra build` 使用 |
| `middleware`   | `mastra build` 的中介軟件配置                   |

使用適配器時，請直接透過框架配置這些功能。例如，使用 Hono 或 Express 的內置 CORS 依賴套件加入 CORS 中介軟件，並在呼叫框架的 listen 函數時設定連接埠。

## MCP 支援

如果 Mastra 實例已配置 MCP 伺服器，伺服器適配器會在 `registerRoutes()` 期間註冊 MCP（Model Context Protocol）路由。MCP 讓外部 Tool 及服務連接至你的 Mastra 伺服器，並與 Agent 互動。

適配器會同時為 HTTP 及 SSE（Server-Sent Events）傳輸方式註冊路由，以支援不同的用戶端連接模式。

### Serverless 模式

對於 Cloudflare Workers 或 Vercel Edge 等 serverless 環境，請透過 `mcpOptions` 啟用無狀態模式。

使用 Mastra deployer（標準 `mastra dev`／`mastra build` 路徑）時，請在伺服器配置中設定 `mcpOptions`：

```typescript
const mastra = new Mastra({
  server: {
    mcpOptions: {
      serverless: true,
    },
  },
})
```

手動建立伺服器適配器時，請直接傳入 `mcpOptions`：

```typescript
const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
})
```

設定 `serverless: true` 後，MCP HTTP 請求會在沒有 session 管理的情況下執行，因而能與無狀態執行環境兼容。

有關配置詳情及如何設定 MCP 伺服器，請參閱 [MCP](https://mastra.zisheng.pro/zh-HK/docs/mcp/overview)。

## 相關內容

- [Hono 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/hono-adapter) - Hono 專用設定
- [Express 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/express-adapter) - Express 專用設定
- [NestJS 適配器](https://mastra.zisheng.pro/zh-HK/reference/server/nestjs-adapter) - NestJS 專用設定
- [自訂適配器](https://mastra.zisheng.pro/zh-HK/docs/server/custom-adapters) - 為其他框架建立適配器
- [伺服器配置](https://mastra.zisheng.pro/zh-HK/docs/server/mastra-server) - 改用 `mastra build`
- [身份驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth) - 為伺服器配置身份驗證
- [MastraServer 參考資料](https://mastra.zisheng.pro/zh-HK/reference/server/mastra-server) - 完整 API 參考資料
- [createRoute() 參考資料](https://mastra.zisheng.pro/zh-HK/reference/server/create-route) - 建立型別安全的自訂路由