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

# NestJS adapter

`@mastra/nestjs` 套件提供 NestJS module，讓 Mastra 可在以 Express 為基礎的 NestJS 平台運行。

v1 刻意只支援 Express。如 Nest 使用其他 HTTP adapter 啟動，`MastraModule` 會在啟動期間拋出錯誤，而不會嘗試局部整合。有關一般 adapter 概念，請參閱 [Server adapter](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)。

## 安裝

安裝 NestJS adapter，並確保 app 使用 Express 平台：

**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
```

## 使用範例

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

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

> **備註:** `MastraModule` 會註冊 catch-all controller（`@All('*')`）。如在 app module 之前匯入，它可能會攔截不相關的 route 並傳回 404。為免衝突，請最後才匯入 `MastraModule`，或將其掛載於專用前綴下（例如 `/api/v1/mastra`）。

```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()
```

Mastra route 預設掛載於 `/api` 下。使用 `prefix` 可更改此設定。

## Module 選項

**mastra** (`Mastra`): Mastra instance

**prefix** (`string`): Route 路徑前綴（例如 /api/v2） (Default: `` `/api` ``)

**rateLimitOptions** (`{ enabled?: boolean; defaultLimit?: number; windowMs?: number; generateLimit?: number }`): Rate limiting 設定（預設啟用）

**shutdownOptions** (`{ timeoutMs?: number; notifyClients?: boolean }`): Graceful shutdown 設定

**bodyLimitOptions** (`{ maxSize?: number; maxFileSize?: number; tempDir?: string; allowedMimeTypes?: string[] }`): Request body 大小限制

**streamOptions** (`{ redact?: boolean; heartbeatMs?: number }`): Streaming 設定

**tracingOptions** (`{ enabled?: boolean; serviceName?: string }`): OpenTelemetry tracing 設定

**contextOptions** (`{ strict?: boolean; logWarnings?: boolean }`): Request context 解析設定

**customRouteAuthConfig** (`Map<string, boolean>`): 各 route 的 auth 覆寫設定。Key 為 METHOD:PATH。

**tools** (`Record<string, Tool>`): Server 已註冊的 Tool

**taskStore** (`InMemoryTaskStore`): A2A（Agent-to-Agent）操作的 task store

**mcpOptions** (`{ serverless?: boolean; sessionIdGenerator?: () => string }`): MCP transport 選項

**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): 啟用 Mastra token auth。預設停用——大部分 NestJS app 會使用自己的 auth guard。為保持向後兼容，query string apiKey auth 須明確啟用。 (Default: `` `{ enabled: false }` ``)

## 非同步註冊

```typescript
import { Module } from '@nestjs/common'
import { ConfigModule, ConfigService } from '@nestjs/config'
import { MastraModule } from '@mastra/nestjs'
import { Mastra } from '@mastra/core/mastra'

@Module({
  imports: [
    ConfigModule.forRoot(),
    MastraModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        mastra: new Mastra({
          agents: {
            greeter: {
              name: 'greeter',
              description: 'Greets the user',
              model: config.get('MASTRA_MODEL', 'openai/gpt-5-mini'),
            },
          },
        }),
        prefix: config.get('MASTRA_PREFIX', '/api'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}
```

## 存取 Mastra

在 service 中使用 `MASTRA` token 或 `MastraService`：

```typescript
import { Injectable, Inject } from '@nestjs/common'
import { MASTRA, MastraService } from '@mastra/nestjs'
import type { Mastra } from '@mastra/core/mastra'

@Injectable()
export class AgentService {
  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
}

@Injectable()
export class WorkflowService {
  constructor(private readonly mastraService: MastraService) {}
}
```

## MCP route

MCP endpoint 會在 API 前綴下提供：

- `POST /api/mcp/:serverId/mcp`
- `GET /api/mcp/:serverId/sse`
- `POST /api/mcp/:serverId/messages`

## Health route

為兼容基礎設施，操作 endpoint 特意不加前綴：

- `GET /health`
- `GET /ready`
- `GET /info`

## 相關內容

- [Server adapter](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)
- [MastraServer 參考](https://mastra.zisheng.pro/zh-HK/reference/server/mastra-server)