安装

学习如何在你的项目中配置 Better Auth。

安装包

让我们开始将 Better Auth 添加到你的项目中:

npm install better-auth

如果你使用了分离的客户端和服务器设置,请确保在项目的两个部分中都安装 Better Auth。

设置环境变量

在你的项目根目录下创建一个 .env 文件,并添加以下环境变量:

  1. 密钥

用于加密和哈希的密钥值。它必须至少包含 32 个字符,并且使用高熵生成。点击下方按钮生成一个。你也可以使用 openssl rand -base64 32 来生成。

.env
BETTER_AUTH_SECRET=

稍后需要轮换密钥吗?你可以使用 BETTER_AUTH_SECRETS(复数)来轮换到新密钥而不使现有数据失效。有关详细信息,请参阅 secrets 选项

  1. 设置基础 URL
.env
BETTER_AUTH_URL=http://localhost:3000 # 应用程序的基础 URL

创建 Better Auth 实例

在以下位置之一创建一个名为 auth.ts 的文件:

  • 项目根目录
  • lib/ 文件夹
  • utils/ 文件夹

你也可以将这些文件夹中的任意一个嵌套在 src/app/server/ 文件夹下(例如 src/lib/auth.tsapp/lib/auth.ts)。

然后在此文件中导入 Better Auth 并创建你的认证实例。确保使用变量名 auth 导出认证实例,或作为 default 导出。

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

export const auth = betterAuth({
  //...
});

配置数据库

Better Auth 需要数据库来存储用户数据。 你可以轻松配置 Better Auth 以使用 SQLite、PostgreSQL 或 MySQL 等。

如果你未配置数据库,也可以将 Better Auth 配置为无状态模式运行。请参阅 无状态会话管理 获取更多信息。请注意,大多数插件都需要数据库。

auth.ts
import { betterAuth } from "better-auth";
import Database from "better-sqlite3";

export const auth = betterAuth({
    database: new Database("./sqlite.db"),
})
auth.ts
import { betterAuth } from "better-auth";
import { Pool } from "pg";

export const auth = betterAuth({
    database: new Pool({
        // 连接选项
    }),
})
</Tab>

<Tab value="mysql">
```ts title="auth.ts"
import { betterAuth } from "better-auth";
import { createPool } from "mysql2/promise";

export const auth = betterAuth({
    database: createPool({
        // 连接选项
    }),
})
</Tab>
</Tabs>

或者,如果你更喜欢使用 ORM,可以使用内置适配器之一。

<Tabs items={["drizzle", "prisma", "mongodb"]}>
<Tab value="drizzle">
```ts title="auth.ts"
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "@/db"; // 你的 drizzle 实例

export const auth = betterAuth({
    database: drizzleAdapter(db, {
        provider: "pg", // 或 "mysql"、"sqlite"
    }),
});
auth.ts
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
// 如果你的 Prisma 文件路径不同,可以调整导入路径
import { PrismaClient } from "@/generated/prisma/client";

const prisma = new PrismaClient();
export const auth = betterAuth({
    database: prismaAdapter(prisma, {
        provider: "sqlite", // 或 "mysql"、"postgresql" 等
    }),
});
auth.ts
import { betterAuth } from "better-auth";
import { mongodbAdapter } from "better-auth/adapters/mongodb";
import { client } from "@/db"; // 你的 mongodb 客户端

export const auth = betterAuth({
    database: mongodbAdapter(client),
});

如果你的数据库未在上面列出,请查看我们其他支持的 数据库 获取更多信息, 或使用受支持的 ORM 之一。

创建数据库表

Better Auth 包含一个 CLI 工具,可帮助管理库所需的模式。

  • 生成: 此命令生成 ORM 架构或 SQL 迁移文件。

如果你使用的是 Kysely,你可以直接使用 migrate 命令应用迁移。使用 generate 仅在你计划手动应用迁移时需要。

npx auth@latest generate
  • 迁移: 此命令直接在数据库中创建所需的表。(仅适用于内置的 Kysely 适配器)

    npx auth@latest migrate

查阅 CLI 文档 获取更多信息。

如果你想手动创建架构,可以查找 数据库章节 中所需的核心架构。

认证方法

配置你想要使用的认证方法。Better Auth 内置了对电子邮件/密码和社交登录提供商的支持。

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

export const auth = betterAuth({
  //...other options
  emailAndPassword: { 
    enabled: true, 
  }, 
  socialProviders: { 
    github: { 
      clientId: process.env.GITHUB_CLIENT_ID as string, 
      clientSecret: process.env.GITHUB_CLIENT_SECRET as string, 
    }, 
  }, 
});

你还可以通过插件使用更多认证方法,如 Passkey用户名魔法链接 等。

挂载处理程序

为了处理 API 请求,你需要在服务器上设置路由处理程序。

在你的框架的指定捕获路由处理程序中创建一个新文件或路由。该路由应处理路径为 /api/auth/* 的请求(除非你配置了不同的基础路径)。

Better Auth 支持任何具有标准 Request 和 Response 对象的后端框架,并提供流行框架的辅助函数。

/app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth"; // 你的 auth 文件路径
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);
/pages/api/auth/[...all].ts
import { auth } from "@/lib/auth"; // 你的 auth 文件路径
import { toNodeHandler } from "better-auth/node";

// 不允许自动解析请求体,手动解析
export const config = { api: { bodyParser: false } };
export default toNodeHandler(auth.handler);
/server/api/auth/[...all].ts
import { auth } from "~/utils/auth"; // auth 文件路径

export default defineEventHandler((event) => {
    return auth.handler(toWebRequest(event));
});
hooks.server.ts
import { auth } from "$lib/auth"; // auth 文件路径
import { svelteKitHandler } from "better-auth/svelte-kit";
import { building } from '$app/environment'

export async function handle({ event, resolve }) {
    return svelteKitHandler({ event, resolve, auth, building });
}
/app/routes/api.auth.$.ts
import { auth } from '~/lib/auth.server' // 根据需要调整路径
import type { LoaderFunctionArgs, ActionFunctionArgs } from "react-router" // 或 "@remix-run/node"

export async function loader({ request }: LoaderFunctionArgs) {
    return auth.handler(request)
}

export async function action({ request }: ActionFunctionArgs) {
    return auth.handler(request)
}
/routes/api/auth/*all.ts
import { auth } from "~/lib/auth"; // auth 文件路径
import { toSolidStartHandler } from "better-auth/solid-start";

export const { GET, POST } = toSolidStartHandler(auth);
src/index.ts
import { Hono } from "hono";
import { auth } from "./auth"; // auth 文件路径
import { serve } from "@hono/node-server";
import { cors } from "hono/cors";

const app = new Hono();

app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw));

serve(app);
src/index.ts
import { auth } from "./auth"; // auth 文件路径

export default {
    async fetch(request: Request) {
        const url = new URL(request.url);

        // 处理认证路由
        if (url.pathname.startsWith("/api/auth")) {
            return auth.handler(request);
        }

        // 处理其他路由
        return new Response("Not found", { status: 404 });
    },
};

Node.js AsyncLocalStorage 支持: Better Auth 使用 AsyncLocalStorage 进行异步上下文跟踪。要在 Cloudflare Workers 中启用此功能,请在 wrangler.toml 中添加 nodejs_compat 标志:

wrangler.toml
compatibility_flags = ["nodejs_compat"]
compatibility_date = "2024-09-23"

或者,如果只需要 AsyncLocalStorage 支持:

wrangler.toml
compatibility_flags = ["nodejs_als"]

在下一个主要版本中,我们将默认假设支持 AsyncLocalStorage,因此此配置将成为必需。

ExpressJS v5 引入了路由匹配的重大变更,切换到 path-to-regexp@6。通配符路由 * 现在应使用新的命名语法书写,例如 /{*any},以正确捕获捕获所有模式。这确保了跨路由场景的兼容性和可预测行为。 有关详细信息,请参阅 Express v5 迁移指南

因此,ExpressJS v5 中的实现应如下所示:

app.all('/api/auth/{*any}', toNodeHandler(auth));

名称 any 是任意的,可以用你喜欢的任何标识符替换。

server.ts
import express from "express";
import { toNodeHandler } from "better-auth/node";
import { auth } from "./auth";

const app = express();
const port = 8000;

app.all("/api/auth/*", toNodeHandler(auth));

// 在 Better Auth 处理器之后挂载 Express JSON 中间件
// 或仅将其应用于与 Better Auth 无交互的路由
app.use(express.json());

app.listen(port, () => {
    console.log(`Better Auth 应用程序已监听端口 ${port}`);
});

这也适用于任何其他 Node.js 服务器框架,如 express、fastify、hapi 等,但可能需要一些修改。参见 fastify 指南。注意不支持 CommonJS (cjs)。

/pages/api/auth/[...all].ts
import type { APIRoute } from "astro";
import { auth } from "@/auth"; // auth 文件路径

export const GET: APIRoute = async (ctx) => {
    return auth.handler(ctx.request);
};

export const POST: APIRoute = async (ctx) => {
    return auth.handler(ctx.request);
};
import { Elysia, Context } from "elysia";
import { auth } from "./auth";

const betterAuthView = (context: Context) => {
    const BETTER_AUTH_ACCEPT_METHODS = ["POST", "GET"]
    // 验证请求方法
    if(BETTER_AUTH_ACCEPT_METHODS.includes(context.request.method)) {
        return auth.handler(context.request);
    } else {
        context.error(405)
    }
}

const app = new Elysia().all("/api/auth/*", betterAuthView).listen(3000);

console.log(
`🦊 Elysia 正在运行于 ${app.server?.hostname}:${app.server?.port}`
);
src/routes/api/auth/$.ts
import { auth } from '@/lib/auth'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/auth/$')({
    server: {
        handlers: {
            GET: async ({ request }:{ request: Request }) => {
                return await auth.handler(request)
            },
            POST: async ({ request }:{ request: Request }) => {
                return await auth.handler(request)
            },
        },
    },
})

当调用需要设置 Cookie 的函数(如 signInEmailsignUpEmail)时,你需要处理 TanStack Start 的 Cookie 设置。Better Auth 提供了 tanstackStartCookies 插件来自动处理此问题。

对于 React(TanStack Start with React):

src/lib/auth.ts
import { betterAuth } from "better-auth";
import { tanstackStartCookies } from "better-auth/tanstack-start";

export const auth = betterAuth({
    //...your config
    plugins: [tanstackStartCookies()] // 确保这是数组中的最后一个插件
})

对于 Solid.js(TanStack Start with Solid):

src/lib/auth.ts
import { betterAuth } from "better-auth";
import { tanstackStartCookies } from "better-auth/tanstack-start/solid";

export const auth = betterAuth({
    //...your config
    plugins: [tanstackStartCookies()] // 确保这是数组中的最后一个插件
})

现在,当调用设置 Cookie 的函数时,它们将自动使用 TanStack Start 的 Cookie 处理系统进行设置。

app/api/auth/[...all]+api.ts
import { auth } from '@/lib/server/auth'; // auth 文件路径

const handler = auth.handler;
export { handler as GET, handler as POST };

创建客户端实例

客户端库帮助你与认证服务器进行交互。Better Auth 为所有流行的 Web 框架提供了客户端,包括原生 JavaScript。

  1. 从对应框架的包中导入 createAuthClient(例如,在 React 中导入 "better-auth/react")。
  2. 调用该函数来创建你的客户端。
  3. 传入你的认证服务器的基础 URL。(如果认证服务器与客户端运行在同一个域上,可以跳过此步骤。)

如果你使用的不是 /api/auth 的基础路径,请确保传入完整的 URL,包括路径。(例如 http://localhost:3000/custom-path/auth

lib/auth-client.ts
import { createAuthClient } from "better-auth/client"
export const authClient = createAuthClient({
    /** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
    baseURL: "http://localhost:3000"
})
lib/auth-client.ts
import { createAuthClient } from "better-auth/react"
export const authClient = createAuthClient({
    /** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
    baseURL: "http://localhost:3000"
})
lib/auth-client.ts
import { createAuthClient } from "better-auth/vue"
export const authClient = createAuthClient({
    /** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
    baseURL: "http://localhost:3000"
})
lib/auth-client.ts
import { createAuthClient } from "better-auth/svelte"
export const authClient = createAuthClient({
    /** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
    baseURL: "http://localhost:3000"
})
lib/auth-client.ts
import { createAuthClient } from "better-auth/solid"
export const authClient = createAuthClient({
    /** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
    baseURL: "http://localhost:3000"
})

提示:如果你只想导出特定方法,可以这样做:

export const { signIn, signUp, useSession } = createAuthClient()

🎉 完成!

完成!现在你可以在应用程序中使用 better-auth 了。继续阅读 基础用法 学习如何使用认证实例来登录用户。