# 多会话 (/docs/plugins/multi-session)

了解如何在 Better Auth 中使用多会话插件。



多会话插件允许用户在同一个浏览器中跨不同账户保持多个活跃会话。该插件适用于需要在多个账户之间切换而无需登出的应用。

## 安装 [#安装]

<Steps>
  <Step>
    ### 将插件添加到你的 **auth** 配置 [#将插件添加到你的-auth-配置]

    ```ts title="auth.ts"
    import { betterAuth } from "better-auth"
    import { multiSession } from "better-auth/plugins"  // [!code highlight]

    export const auth = betterAuth({
        plugins: [
            multiSession(), // [!code highlight]
        ]
    })
    ```
  </Step>

  <Step>
    ### 添加客户端插件 [#添加客户端插件]

    添加多会话客户端插件，以启用对多个活跃会话的管理。

    ```ts title="auth-client.ts"
    import { createAuthClient } from "better-auth/client"
    import { multiSessionClient } from "better-auth/client/plugins"  // [!code highlight]

    export const authClient = createAuthClient({
        plugins: [
            multiSessionClient()  // [!code highlight]
        ]
    })
    ```
  </Step>
</Steps>

## 使用 [#使用]

每当用户登录时，插件会在浏览器中添加额外的 Cookie。该 Cookie 将用于在不同账户之间维护多个会话。

要列出当前用户的所有活跃会话，可以调用 `listDeviceSessions` 方法。

**Endpoint:** `GET /multi-session/list-device-sessions`

### Client Side

```ts
const { data, error } = await authClient.multiSession.listDeviceSessions();
```

### Server Side

```ts
const data = await auth.api.listDeviceSessions({
    // This endpoint requires session cookies.
    headers: await headers(),
});
```

### Type Definition

```ts
type listDeviceSessions = {
}
```

### 设置活动会话 [#设置活动会话]

要设置活动会话，可以调用 `setActive` 方法。

**Endpoint:** `POST /multi-session/set-active`

### Client Side

```ts
const { data, error } = await authClient.multiSession.setActive({
    sessionToken: "some-session-token", // required, 要设置为活跃的会话令牌。
});
```

### Server Side

```ts
const data = await auth.api.setActiveSession({
    body: {
        sessionToken: "some-session-token", // required, 要设置为活跃的会话令牌。
    },
    // This endpoint requires session cookies.
    headers: await headers(),
});
```

### Type Definition

```ts
type setActiveSession = {
    /**
     * 要设置为活跃的会话令牌。
     */
    sessionToken: string = "some-session-token"
}
```

### 撤销会话 [#撤销会话]

要撤销会话，可以调用 `revoke` 方法。

**Endpoint:** `POST /multi-session/revoke`

### Client Side

```ts
const { data, error } = await authClient.multiSession.revoke({
    sessionToken: "some-session-token", // required, 要撤销的会话令牌。
});
```

### Server Side

```ts
const data = await auth.api.revokeDeviceSession({
    body: {
        sessionToken: "some-session-token", // required, 要撤销的会话令牌。
    },
    // This endpoint requires session cookies.
    headers: await headers(),
});
```

### Type Definition

```ts
type revokeDeviceSession = {
    /**
     * 要撤销的会话令牌。
     */
    sessionToken: string = "some-session-token"
}
```

### 登出并撤销所有会话 [#登出并撤销所有会话]

当用户登出时，插件会撤销该用户的所有活跃会话。你可以调用现有的 `signOut` 方法，它会自动处理撤销所有会话。

### 最大会话数 [#最大会话数]

你可以通过向插件传递 `maximumSessions` 选项来指定用户允许的最大会话数。默认情况下，插件允许每个设备最多 5 个会话。

```ts title="auth.ts"
import { betterAuth } from "better-auth"
import { multiSession } from "better-auth/plugins"

export const auth = betterAuth({
    plugins: [
        multiSession({
            maximumSessions: 3
        })
    ]
})
```