安装

安装包

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

npm install better-auth

设置环境变量

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

1. 密钥

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

BETTER_AUTH_SECRET=

2. 设置基础 URL

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 导出认证实例，或作为 default 导出。

import { betterAuth } from "better-auth";

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

配置数据库

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

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

export const auth = betterAuth({
    database: new Database("./sqlite.db"),
})

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

创建数据库表

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

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

npx auth@latest generate

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

  npm

  pnpm

  yarn

  bun

  npx auth@latest migrate

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

认证方法

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

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, 
    }, 
  }, 
});

挂载处理程序

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

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

import { auth } from "@/lib/auth"; // 你的 auth 文件路径
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);

创建客户端实例

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

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

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

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

🎉 完成！

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