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

# Better Auth

`@mastra/auth-better-auth` 套件透過 Better Auth 為 Mastra 提供驗證功能。它會使用你的 Better Auth 執行個體驗證傳入的請求，並透過 `server.auth` 選項與 Mastra 伺服器整合。

## 先決條件

此範例使用 Better Auth。請確認已設定 Better Auth 執行個體與環境變數。

```env
# Required by Better Auth
BETTER_AUTH_SECRET=...   # at least 32 chars
BETTER_AUTH_URL=http://localhost:3000

# Example DB URL used by the snippet below (adjust for your setup)
DATABASE_URL=postgres://...
```

> **備註:** 為了安全性與穩定性，Better Auth 建議明確設定 `baseURL`（或透過 `BETTER_AUTH_URL` 設定）。

如果尚未掛載 Better Auth 的處理常式（讓應用程式可以登入使用者及建立工作階段），請依照 [Better Auth 安裝指南](https://www.better-auth.com/docs/installation)掛載 `/api/auth/*` 路由（或你設定的基礎路徑）。

## 安裝

安裝 `@mastra/auth-better-auth` 套件：

**npm**:

```bash
npm install @mastra/auth-better-auth
```

**pnpm**:

```bash
pnpm add @mastra/auth-better-auth
```

**Yarn**:

```bash
yarn add @mastra/auth-better-auth
```

**Bun**:

```bash
bun add @mastra/auth-better-auth
```

## 使用範例

首先，建立 Better Auth 執行個體：

```ts
import { betterAuth } from 'better-auth'

export const auth = betterAuth({
  database: {
    provider: 'postgresql',
    url: process.env.DATABASE_URL!,
  },
  emailAndPassword: {
    enabled: true,
  },
  baseURL: process.env.BETTER_AUTH_URL,
  secret: process.env.BETTER_AUTH_SECRET,
})
```

接著，將它與 Mastra 搭配使用：

```ts
import { Mastra } from '@mastra/core'
import { MastraAuthBetterAuth } from '@mastra/auth-better-auth'
import { auth } from '@/lib/auth'

const mastraAuth = new MastraAuthBetterAuth({
  auth,
})

export const mastra = new Mastra({
  server: {
    auth: mastraAuth,
  },
})
```

請參閱 [MastraAuthBetterAuth](https://mastra.zisheng.pro/zh-TW/reference/auth/better-auth)，瞭解所有可用的設定選項。

## 自訂授權

```ts
const mastraAuth = new MastraAuthBetterAuth({
  auth,
  async authorizeUser(user) {
    // Example: only allow verified emails
    return user?.user?.emailVerified === true
  },
})
```

## 路由設定

```ts
const mastraAuth = new MastraAuthBetterAuth({
  auth,
  public: ['/health', '/api/status'],
  protected: ['/api/*', '/admin/*'],
})
```

### 比對規則

- `public` 與 `protected` 接受完整路徑、萬用字元模式（例如 `/api/*`）及路徑參數（例如 `/users/:id`）。
- 若要設定特定 HTTP 方法的規則，請使用 `["/api/agents", ["GET", "POST"]]` 這類元組。
- 如果路由同時符合 `public` 與 `protected`，則以 `public` 為優先，不需要驗證。
- 如果兩者都不符合，預設會將路由視為受保護（除非路由明確標記為 `requiresAuth: false`）。

## 用戶端設定

啟用驗證後，向 Mastra 內建路由發出的請求必須通過驗證。實際上，這表示用戶端必須傳送 Better Auth 設定用來驗證請求的憑證。

### Cookie 工作階段（建議）

如果 Better Auth 設定使用 Cookie，請將用戶端設定為傳送憑證。若為跨來源請求（例如在 `:3000` 執行的 Next.js 呼叫位於 `:4111` 的 Mastra），請在 Mastra 伺服器上啟用 CORS 憑證：

```ts
export const mastra = new Mastra({
  server: {
    auth: mastraAuth,
    cors: {
      origin: 'http://localhost:3000', // your frontend origin
      credentials: true,
    },
  },
})
```

接著，設定用戶端以包含憑證：

```ts
import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})
```

如果直接呼叫 API，也請在 `fetch` 中包含憑證：

```ts
await fetch('http://localhost:4111/api/agents/weatherAgent/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({ messages: 'Weather in London' }),
})
```

### Bearer 權杖

你可以將已簽署的工作階段權杖當作 Bearer 權杖傳送。請從 Better Auth 用戶端工作階段取得權杖，並將其加入 `Authorization` 標頭：

```ts
import { MastraClient } from '@mastra/client-js'
import { authClient } from './auth-client' // your Better Auth client

const session = await authClient.getSession()

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  headers: {
    Authorization: `Bearer ${session.data?.session.token}`,
  },
})
```

請參閱 [Mastra Client SDK](https://mastra.zisheng.pro/zh-TW/docs/server/mastra-client)，瞭解更多設定選項。

### 發出已驗證的請求

**React**:

```tsx
import { mastraClient } from '../lib/mastra-client'

export const TestAgent = () => {
  async function handleClick() {
    const agent = mastraClient.getAgent('weatherAgent')

    const response = await agent.generate('Weather in London')

    console.log(response)
  }

  return <button onClick={handleClick}>Test Agent</button>
}
```

**cURL**:

```bash
curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "messages": "Weather in London"
  }'
```

## 疑難排解

- **每個請求都傳回 401**：確認已掛載 Better Auth 處理常式，且應用程式可以建立有效的工作階段。請檢查用戶端是否傳送工作階段 Cookie 或 `Authorization: Bearer <signed-token>` 標頭。
- **跨來源時未傳送 Cookie**：在 `MastraClient` 中設定 `credentials: "include"`，並以你的前端來源及 `credentials: true` 設定 `server.cors`。
- **Bearer 權杖遭拒**：請確認傳入完整的已簽署工作階段權杖（來自 `authClient.getSession()`），而非原始或未簽署的權杖。
- **基礎 URL 問題**：在 `betterAuth({ ... })` 中設定 `baseURL`，或設定 `BETTER_AUTH_URL`。
- **資料庫連線錯誤**：確認 `DATABASE_URL` 及資料庫 Provider 設定。