安装 | Better Auth 中文文档

安装包

首先将 Better Auth 添加到您的项目中：

npm install better-auth

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

设置环境变量

在项目根目录下创建一个 .env 文件，并添加以下环境变量：

密钥

库用于加密和生成哈希的随机值。您可以使用下面的按钮生成一个，或者使用 openssl 等工具。

.env

BETTER_AUTH_SECRET=

设置基础 URL

.env

BETTER_AUTH_URL=http://localhost:3000 # 您应用的基础 URL

创建 Better Auth 实例

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

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

您也可以将这些文件夹嵌套在 src/、app/ 或 server/ 文件夹下（例如 src/lib/auth.ts、app/lib/auth.ts）。

在此文件中，导入 Better Auth 并创建您的 auth 实例。确保使用变量名 auth 或作为 default 导出方式导出 auth 实例。

auth.ts

import { betterAuth } from "better-auth";

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

配置数据库

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

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({
        // 连接选项
    }),
})

auth.ts

import { betterAuth } from "better-auth";
import { createPool } from "mysql2/promise";

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

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

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";

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 工具来帮助管理库所需的模式。

Generate：此命令生成 ORM 模式或 SQL 迁移文件。

如果您使用 Kysely，可以通过下面的 migrate 命令直接应用迁移。只有在计划手动应用迁移时才使用 generate。

Terminal

npx @better-auth/cli generate

Migrate：此命令直接在数据库中创建所需的表。（仅适用于内置的 Kysely 适配器）

Terminal

npx @better-auth/cli migrate

有关更多信息，请参阅 CLI 文档。

如果您希望手动创建模式，可以在数据库部分找到所需的核心模式。

认证方法

配置您想要使用的认证方法。Better Auth 内置支持邮箱/密码认证以及社交登录提供商。

auth.ts

import { betterAuth } from "better-auth";

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

您还可以通过插件使用更多认证方法，例如 Passkey（通行密钥）、用户名、Magic Link（魔法链接）等。

挂载处理程序

要处理 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);

/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 "@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);

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 app listening on port ${port}`);
});

这也适用于任何其他 Node 服务器框架，如 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 is running at ${app.server?.hostname}:${app.server?.port}`
);

src/routes/api/auth/$.ts

import { auth } from '~/lib/server/auth'
import { createServerFileRoute } from '@tanstack/react-start/server'

export const ServerRoute = createServerFileRoute('/api/auth/$').methods({
GET: ({ request }) => {
    return auth.handler(request)
},
POST: ({ request }) => {
    return auth.handler(request)
},
});

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。

从适用于您框架的包中导入 createAuthClient（例如，React 使用 "better-auth/react"）。
调用该函数来创建您的客户端。
传递您身份验证服务器的基本 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 了。继续阅读基础用法来学习如何使用 auth 实例进行用户登录。

开始使用

概念

身份验证

数据库

集成

插件

指南

参考

安装

On this page