# Anonymous (/docs/plugins/anonymous)

Better Auth 的 Anonymous 插件。



Anonymous 插件允许用户在不提供电子邮件地址、密码、OAuth 提供商或任何其他个人身份信息（PII）的情况下获得身份验证体验。用户稍后可以在准备好时将认证方式关联到其账户。

## 安装 [#安装]

<Steps>
  <Step>
    ### 将插件添加到您的身份验证配置中 [#将插件添加到您的身份验证配置中]

    要启用匿名身份验证，请将 anonymous 插件添加到您的身份验证配置中。

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

    export const auth = betterAuth({
        // ... 其他配置选项
        plugins: [
            anonymous() // [!code highlight]
        ]
    })
    ```
  </Step>

  <Step>
    ### 迁移数据库 [#迁移数据库]

    运行迁移或生成模式以向数据库添加必要的字段和表。

    <Tabs items="[&#x22;migrate&#x22;, &#x22;generate&#x22;]">
      <Tab value="migrate">
        <CodeBlockTabs defaultValue="npm" groupId="persist-install">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx auth migrate
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx auth migrate
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx auth migrate
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x auth migrate
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>

      <Tab value="generate">
        <CodeBlockTabs defaultValue="npm" groupId="persist-install">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx auth generate
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx auth generate
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx auth generate
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x auth generate
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>
    </Tabs>

    请参见 [模式](#schema) 部分以手动添加字段。
  </Step>

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

    接下来，在您的身份验证客户端实例中包含匿名客户端插件。

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

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

## 用法 [#用法]

### 匿名登录 [#匿名登录]

要让用户匿名登录，请使用 `signIn.anonymous()` 方法。此方法会使用生成的电子邮件地址和配置的或默认的名称创建新用户，然后建立会话。

**Endpoint:** `POST /sign-in/anonymous`

### Client Side

```ts
const { data, error } = await authClient.signIn.anonymous();
```

### Server Side

```ts
const data = await auth.api.signInAnonymous();
```

### Type Definition

```ts
type signInAnonymous = {
}
```

<Callout type="info">
  如果当前会话属于匿名用户，再次调用 `signIn.anonymous()` 将返回错误，以防止创建另一个匿名用户。请使用其他身份验证方法关联当前账户，或先登出再开始新的匿名会话。
</Callout>

### 关联账户 [#关联账户]

如果用户已匿名登录，并尝试使用其他方法进行 `signIn` 或 `signUp`，他们的匿名活动可以关联到新账户。

为此，您需要先向插件提供 `onLinkAccount` 回调。

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

export const auth = betterAuth({
    plugins: [
        anonymous({
            onLinkAccount: async ({ anonymousUser, newUser }) => {
               // 执行操作，例如将购物车商品从匿名用户转移到新用户
            }
        })
    ]
```

然后，当您使用其他方法调用 `signIn` 或 `signUp` 时，`onLinkAccount` 回调将被调用。默认情况下，`anonymousUser` 会被删除。

```ts
import { authClient } from "@/lib/auth-client";

const user = await authClient.signIn.email({
    email,
})
```

### 删除匿名用户 [#删除匿名用户]

要删除匿名用户，您可以调用 `/delete-anonymous-user` 端点。

**Endpoint:** `POST /delete-anonymous-user`

### Client Side

```ts
await authClient.deleteAnonymousUser();
```

### Server Side

```ts
await auth.api.deleteAnonymousUser();
```

### Type Definition

```ts
type deleteAnonymousUser = {
}
```

<Callout type="info">
  **说明:**

  * 默认情况下，当账户关联到新的认证方法时，匿名用户会被自动删除。
  * 将 `disableDeleteAnonymousUser` 设置为 `true` 将阻止匿名用户调用 `/delete-anonymous-user` 端点。
</Callout>

## 选项 [#选项]

### `emailDomainName` [#emaildomainname]

用于为匿名用户生成电子邮件地址的域名。如果未提供，则使用默认格式 `{id}@anonymous.placeholder.invalid`。

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

export const auth = betterAuth({
    plugins: [
        anonymous({
            emailDomainName: "example.com" // [!code highlight] -> temp-{id}@example.com
        })
    ]
})
```

### `generateRandomEmail` [#generaterandomemail]

用于为匿名用户生成电子邮件地址的自定义函数。允许您定义自己的邮箱格式。该函数可以是同步或异步的。

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

export const auth = betterAuth({
    plugins: [
        anonymous({
            generateRandomEmail: () => { // [!code highlight]
                const id = crypto.randomUUID() // [!code highlight]
                return `guest-${id}@example.com` // [!code highlight]
            } // [!code highlight]
        })
    ]
})
```

<Callout type="info">
  **说明:**

  * 如果提供了 `generateRandomEmail`，则会忽略 `emailDomainName`。
  * 您负责确保电子邮件地址的唯一性以避免冲突。返回的电子邮件必须为有效格式。
</Callout>

### `onLinkAccount` [#onlinkaccount]

当匿名用户将账户关联到新的认证方法时调用的回调函数。回调接收一个包含 `anonymousUser` 和 `newUser` 的对象。

### `disableDeleteAnonymousUser` [#disabledeleteanonymoususer]

默认情况下，当匿名用户将账户关联到新的认证方法时，会自动删除匿名用户记录。
如果您将此选项设置为 `true`，则自动删除将被禁用，
并且匿名用户将无法访问 `/delete-anonymous-user` 端点。

### `generateName` [#generatename]

调用此回调函数以为匿名用户生成名称。如果您想为匿名用户生成随机名称，或数据库中 `name` 字段为唯一时，此选项非常有用。

## 模式 [#模式]

Anonymous 插件需要在用户表中添加一个额外字段：



<DatabaseTable name="user" fields="anonymousUserTableFields" />