安装 | Better Auth 中文文档

安装包

让我们从将 Better Auth 添加到您的项目开始：

npm install better-auth

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

设置环境变量

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

密钥

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

.env

BETTER_AUTH_SECRET=

设置 Base URL

.env

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

创建 Better Auth 实例

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

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

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

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

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({
        // connection options
    }),
})

auth.ts

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

export const auth = betterAuth({
    database: createPool({
        // connection options
    }),
})

或者，如果您更喜欢使用 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、username、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"]
    // validate request method
    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 };

创建客户端实例

客户端库帮助您与 auth 服务器交互。Better Auth 为所有流行 Web 框架提供客户端，包括 vanilla JavaScript。

从您的框架的包中导入 createAuthClient（例如，对于 React，使用 "better-auth/react"）。
调用函数创建您的客户端。
传递您的 auth 服务器的基础 URL。（如果 auth 服务器与您的客户端运行在同一域上，您可以跳过此步骤。）

如果您使用不同于 /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