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

# Server 介面卡

Server 介面卡可讓你使用自己的 HTTP 伺服器執行 Mastra，而不使用 `mastra build` 產生的 Hono 伺服器。你可以更完整地控制伺服器設定，包括自訂中介軟體順序、驗證、記錄記錄及部署設定。你仍可將 Mastra 整合至任何 Node.js 應用程式，且不必變更 Agent 或 Workflow 的執行方式。

> **警告:** Server 介面卡會使用你傳入的 `mastra` 執行個體，且不會執行檔案式探索。請在程式碼中將 Agent 註冊至該執行個體。若要使用檔案式 Agent，請透過 `mastra dev` 或 `mastra build` 將 Mastra 作為獨立伺服器執行。

## 何時使用 Server 介面卡

- 你想要自動將 Mastra 的端點新增至現有應用程式
- 你需要直接存取伺服器執行個體以進行自訂設定
- 你的團隊偏好使用其他伺服器框架，而非 `mastra build` 建立的 Hono 伺服器。

> **提示:** 若部署沒有自訂伺服器需求，請改用 `mastra build`。它會設定伺服器並註冊中介軟體，也會依據專案設定套用部署設定。請參閱 [Server 設定](https://mastra.zisheng.pro/zh-TW/docs/server/mastra-server)。
>
> 若要搭配 Server 介面卡使用 [Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview)，請使用 [`mastra studio`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)，僅啟動 Studio UI。

## 可用的介面卡

Mastra 目前提供下列官方 Server 介面卡：

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

你也可以建置自己的介面卡，詳情請閱讀[自訂介面卡](https://mastra.zisheng.pro/zh-TW/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
```

## 設定

如常初始化應用程式，接著傳入 `app` 以及來自 `src/mastra/index.ts` 的主要 `mastra` 執行個體，以建立 `MastraServer`。呼叫 `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-TW/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-TW/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-TW/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-TW/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-TW/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` 等路由中繼資料，請優先使用 `registerApiRoute()`。
- 直接將路由掛載至框架應用程式時，若這些路由需要 Mastra 驗證，請使用介面卡匯出的 `createAuthMiddleware()` 輔助函式。

如需更多資訊，請參閱 Express 與 Hono 的「新增自訂路由」章節：[Express](https://mastra.zisheng.pro/zh-TW/reference/server/express-adapter)及 [Hono](https://mastra.zisheng.pro/zh-TW/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 工具整合。設定 `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-TW/reference/server/mastra-server)。

## 各路由的驗證覆寫

在 Mastra 執行個體上設定驗證後，所有路由預設皆須通過驗證。有時你會需要例外，例如公開的健康狀態檢查端點或 webhook 接收器；也可能需要控制更嚴格的管理員路由。

使用 `customRouteAuthConfig` 覆寫特定路由的驗證行為。鍵採用 `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-TW/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()
```

兩種方法都會傳回相同的應用程式執行個體。請依目前作用域選用較方便的方法。

## Server 設定與介面卡選項

使用 Server 介面卡時，設定來自兩處：傳給 `Mastra` 建構函式的 Mastra `server` 設定，以及介面卡建構函式選項。瞭解各選項的來源，有助於避免設定看似未生效時產生混淆。

### 介面卡會使用的設定

介面卡會從 `mastra.getServer()` 讀取下列設定：

| 選項              | 說明                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `auth`          | 驗證設定，由 `registerAuthMiddleware()` 使用。                                                                     |
| `bodySizeLimit` | 預設本文大小上限（位元組）。可透過 `bodyLimitOptions` 針對各介面卡覆寫。                                                            |
| `onError`       | 路由處理常式發生未處理錯誤時呼叫的自訂錯誤處理常式。請參閱 [server.onError](https://mastra.zisheng.pro/zh-TW/reference/configuration)。 |

### 僅限介面卡建構函式

這些選項會直接傳給介面卡建構函式，不會從 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`    | `mastra build` 的 `registerApiRoute()` |
| `middleware`   | `mastra build` 的中介軟體設定                |

使用介面卡時，請直接透過框架設定這些功能。例如，使用 Hono 或 Express 的內建 CORS 套件新增 CORS 中介軟體，並在呼叫框架的 listen 函式時設定連接埠。

## MCP 支援

若 Mastra 執行個體已設定 MCP 伺服器，Server 介面卡會在 `registerRoutes()` 期間註冊 MCP（Model Context Protocol）路由。MCP 可讓外部工具與服務連線至 Mastra 伺服器，並與 Agent 互動。

介面卡會同時為 HTTP 與 SSE（Server-Sent Events）傳輸註冊路由，支援不同的用戶端連線模式。

### Serverless 模式

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

使用 Mastra 部署程式（標準 `mastra dev`／`mastra build` 路徑）時，請在 Server 設定中設定 `mcpOptions`：

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

手動建立 Server 介面卡時，請直接傳入 `mcpOptions`：

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

當 `serverless: true` 時，MCP HTTP 請求不使用工作階段管理，因此可與無狀態執行環境相容。

如需設定詳細資料及 MCP 伺服器設定方式，請參閱 [MCP](https://mastra.zisheng.pro/zh-TW/docs/mcp/overview)。

## 相關內容

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