# 性能优化 (/docs/guides/optimizing-for-performance)

优化 Better Auth 应用性能的指南。



在本指南中，我们将介绍一些优化应用性能的方法，以构建更高效的 Better Auth 应用。

## 缓存 [#缓存]

缓存是一种强大的技术，能够显著提升 Better Auth 应用的性能，减少数据库查询次数并加快响应速度。

### Cookie 缓存 [#cookie-缓存]

每次调用 `useSession` 或 `getSession` 都访问数据库并不理想，尤其是在会话不经常变化的情况下。Cookie 缓存通过将会话数据存储在短期有效且签名过的 Cookie 中来解决此问题，这类似于使用刷新令牌的 JWT 访问令牌。

要开启 Cookie 缓存，只需在认证配置中设置 `session.cookieCache`：

```ts title="auth.ts"
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  session: {
    cookieCache: {
      enabled: true,
      maxAge: 5 * 60, // 缓存时长，单位秒
    },
  },
});
```

阅读更多关于[Cookie 缓存](/docs/concepts/session-management#cookie-缓存)的内容。

### 框架缓存 [#框架缓存]

以下是如何在不同框架和环境中实现缓存的示例：

<Tabs items="[&#x22;Next&#x22;, &#x22;react-router&#x22;, &#x22;SolidStart&#x22;, &#x22;TanStack Query&#x22;]">
  <Tab value="Next">
    从 Next v15 起，我们可以使用 `"use cache"` 指令缓存服务器函数的响应。

    ```ts
    export async function getUsers() {
        'use cache' // [!code highlight]
        const { users } = await auth.api.listUsers();
        return users
    }
    ```

    了解更多关于 <Link href="https://nextjs.org/docs/app/api-reference/directives/use-cache">NextJS use cache 指令</Link>。
  </Tab>

  <Tab value="react-router">
    在 React Router v7 中，您可以通过在加载器函数中使用 HTTP `Cache-Control` 头来缓存响应。您还必须导出一个 headers 函数以发送这些头部信息。下面是一个示例：

    ```ts
    import { data } from 'react-router';
    import type { Route } from './+types/your-route-name';

    export const loader = async ({ request }: Route.LoaderArgs) => {
      const { users } = await auth.api.listUsers();
      
      return data(users, {
        headers: {
          'Cache-Control': 'max-age=3600', // 缓存 1 小时
        },
      });
    };

    export function headers({ loaderHeaders }: Route.HeadersArgs) {
      return loaderHeaders;
    }
    ```
  </Tab>

  <Tab value="SolidStart">
    在 SolidStart 中，您可以使用 `query` 函数来缓存数据。示例如下：

    ```tsx
    const getUsers = query(
        async () => (await auth.api.listUsers()).users,
        "getUsers"
    );
    ```

    了解更多关于 SolidStart <Link href="https://docs.solidjs.com/solid-router/reference/data-apis/query">`query` 函数</Link>。
  </Tab>

  <Tab value="TanStack Query">
    使用 TanStack Query，您可以通过 `useQuery` 钩子缓存数据。示例如下：

    ```ts
    import { useQuery } from '@tanstack/react-query';

    const fetchUsers = async () => {
        const { users } = await auth.api.listUsers();
        return users;
    };

    export default function Users() {
        const { data: users, isLoading } = useQuery('users', fetchUsers, {
            staleTime: 1000 * 60 * 15, // 缓存 15 分钟
        });

        if (isLoading) return <div>加载中...</div>;

        return (
            <ul>
                {users.map(user => (
                    <li key={user.id}>{user.name}</li>
                ))}
            </ul>
        );
    }
    ```

    了解更多关于 <Link href="https://tanstack.com/query">TanStack Query</Link>。
  </Tab>
</Tabs>

## 后台任务 [#后台任务]

在无服务器平台（如 Vercel、Cloudflare Workers）上，您可以通过将非关键工作（清理、分析、速率限制更新、邮件发送）延迟到响应发送后执行，来提升响应速度。配置 [`advanced.backgroundTasks`](/docs/reference/options#backgroundtasks) 并在钩子中使用 `ctx.context.runInBackground` 或 `ctx.context.runInBackgroundOrAwait`。

```ts title="auth.ts"
import { betterAuth } from "better-auth";
import { createAuthMiddleware } from "better-auth/api";
import { waitUntil } from "@vercel/functions";

export const auth = betterAuth({
  advanced: {
    backgroundTasks: { handler: waitUntil },
  },
  hooks: {
    after: createAuthMiddleware(async (ctx) => {
      if (ctx.path === "/sign-up/email") {
        ctx.context.runInBackground(logSignUp(ctx.context.newSession?.user.id));
      }
    }),
  },
});
```

有关更多示例，请参阅[上下文文档](/docs/concepts/hooks#runinbackground)。

## SSR 优化 [#ssr-优化]

如果您使用支持服务器端渲染的框架，通常建议在服务器上预取用户会话，并将其作为客户端的回退。

```ts
const session = await auth.api.getSession({
  headers: await headers(),
});
// 然后将 session 传递给客户端
```

## 数据库优化 [#数据库优化]

优化数据库性能对于充分发挥 Better Auth 的性能至关重要。

#### 推荐索引字段 [#推荐索引字段]

| 表名            | 字段                         | 插件           |
| ------------- | -------------------------- | ------------ |
| users         | `email`                    |              |
| accounts      | `userId`                   |              |
| sessions      | `userId`, `token`          |              |
| verifications | `identifier`               |              |
| invitations   | `email`, `organizationId`  | organization |
| members       | `userId`, `organizationId` | organization |
| organizations | `slug`                     | organization |
| passkey       | `userId`                   | passkey      |
| twoFactor     | `secret`                   | twoFactor    |

<Callout>
  我们计划在未来的模式生成工具中添加索引支持。
</Callout>

## 打包体积优化 [#打包体积优化]

如果您使用自定义适配器（如 Prisma、Drizzle 或 MongoDB），可以通过使用 `better-auth/minimal` 替代 `better-auth` 来减小打包体积。该版本排除了仅在直接数据库连接时才需要的 Kysely。

### 使用方法 [#使用方法]

只需从 `better-auth/minimal` 而非 `better-auth` 导入即可：

<Tabs items="[&#x22;Prisma&#x22;, &#x22;Drizzle&#x22;, &#x22;MongoDB&#x22;]">
  <Tab value="Prisma">
    ```ts title="auth.ts"
    import { betterAuth } from "better-auth/minimal"; // [!code highlight]
    import { prismaAdapter } from "better-auth/adapters/prisma";
    import { PrismaClient } from "@prisma/client";

    const prisma = new PrismaClient();

    export const auth = betterAuth({
      database: prismaAdapter(prisma, {
        provider: "postgresql", // 或 "mysql", "sqlite"
      }),
    });
    ```
  </Tab>

  <Tab value="Drizzle">
    ```ts title="auth.ts"
    import { betterAuth } from "better-auth/minimal"; // [!code highlight]
    import { drizzleAdapter } from "better-auth/adapters/drizzle";
    import { db } from "./database";

    export const auth = betterAuth({
      database: drizzleAdapter(db, {
        provider: "pg", // 或 "mysql", "sqlite"
      }),
    });
    ```
  </Tab>

  <Tab value="MongoDB">
    ```ts title="auth.ts"
    import { betterAuth } from "better-auth/minimal"; // [!code highlight]
    import { mongodbAdapter } from "better-auth/adapters/mongodb";
    import { MongoClient } from "mongodb";

    const client = new MongoClient(process.env.DATABASE_URL!);
    const db = client.db();

    export const auth = betterAuth({
      database: mongodbAdapter(db),
    });
    ```
  </Tab>
</Tabs>

<Callout type="warning">
  **限制：**

  * 不支持直接数据库连接（必须使用适配器）
  * 不支持内置迁移。请使用外部迁移工具（如果您需要内置迁移支持，则使用 `better-auth`）
</Callout>