基本用法

Better Auth提供内置的身份验证支持：

  • 邮箱和密码
  • 社交提供商（谷歌、GitHub、苹果等）

同时也可以通过插件轻松扩展，例如：用户名、魔法链接、通行密钥、邮箱一次性密码等。

邮箱和密码

要启用邮箱和密码认证：

auth.ts
import { betterAuth } from "better-auth"
 
export const auth = betterAuth({
    emailAndPassword: {    
        enabled: true
    } 
})

注册

要注册用户，你需要调用客户端方法 signUp.email 并提供用户信息。

sign-up.ts
import { authClient } from "@/lib/auth-client"; //导入认证客户端
 
const { data, error } = await authClient.signUp.email({
        email, // 用户邮箱地址
        password, // 用户密码 -> 默认最少8个字符
        name, // 用户显示名称
        image, // 用户头像URL（可选）
        callbackURL: "/dashboard" // 用户验证邮箱后重定向的URL（可选）
    }, {
        onRequest: (ctx) => {
            //显示加载中
        },
        onSuccess: (ctx) => {
            //重定向到仪表盘或登录页面
        },
        onError: (ctx) => {
            // 显示错误信息
            alert(ctx.error.message);
        },
});

默认情况下，用户成功注册后会自动登录。要禁用此行为，可以将 autoSignIn 设置为 false。

auth.ts
import { betterAuth } from "better-auth"
 
export const auth = betterAuth({
    emailAndPassword: {
    	enabled: true,
    	autoSignIn: false //默认为true
  },
})

登录

要登录，你可以使用客户端提供的 signIn.email 函数。

sign-in
const { data, error } = await authClient.signIn.email({
        /**
         * 用户邮箱
         */
        email,
        /**
         * 用户密码
         */
        password,
        /**
         * 用户验证邮箱后重定向的URL（可选）
         */
        callbackURL: "/dashboard",
        /**
         * 浏览器关闭后记住用户会话。
         * @default true
         */
        rememberMe: false
}, {
    //回调函数
})

要始终从浏览器端调用better-auth提供的客户端方法。不要从服务器调用它们。

服务器端认证

要在服务器上认证用户，你可以使用 auth.api 方法。

server.ts
import { auth } from "./auth"; // 你的Better Auth服务器实例路径
 
const response = await auth.api.signInEmail({
    body: {
        email,
        password
    },
    asResponse: true // 返回响应对象而不是数据
});

如果服务器无法返回响应对象，你需要手动解析并设置cookie。但对于像Next.js这样的框架，我们提供了插件来自动处理这个问题。

社交登录

Better Auth提供多种社交登录，包括谷歌、GitHub、苹果、Discord等。要启用它们，你需要在auth对象的socialProviders选项中配置你需要的社交认证方式。

auth.ts
import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    socialProviders: { 
        github: { 
            clientId: process.env.GITHUB_CLIENT_ID!, 
            clientSecret: process.env.GITHUB_CLIENT_SECRET!, 
        } 
    }, 
})

使用社交方式登录

要使用社交方式登录，你需要调用signIn.social。它接受一个具有以下属性的对象：

sign-in.ts
import { authClient } from "@/lib/auth-client"; //导入认证客户端
 
await authClient.signIn.social({
    /**
     * 社交提供商ID
     * @example "github", "google", "apple"
     */
    provider: "github",
    /**
     * 用户通过提供商认证后重定向的URL
     * @default "/"
     */
    callbackURL: "/dashboard", 
    /**
     * 登录过程中发生错误时重定向的URL
     */
    errorCallbackURL: "/error",
    /**
     * 新注册用户重定向的URL
     */
    newUserCallbackURL: "/welcome",
    /**
     * 禁用自动重定向到提供商。
     * @default false
     */
    disableRedirect: true,
});

你也可以使用社交认证提供的idToken或accessToken进行认证，而不是将用户重定向到认证网站。有关更多详细信息，请参阅社交认证公司提供的技术文档。

退出登录

要退出用户登录，你可以使用客户端提供的signOut函数。

user-card.tsx
await authClient.signOut();

你可以传递fetchOptions在成功时重定向

user-card.tsx
await authClient.signOut({
  fetchOptions: {
    onSuccess: () => {
      router.push("/login"); // 重定向到登录页面
    },
  },
});

会话

一旦用户登录，你可能需要获取用户会话。Better Auth允许你轻松地从服务器和客户端访问会话数据。

客户端

使用会话

Better Auth提供了一个useSession钩子，可以在客户端轻松访问会话数据。这个钩子使用nanostore实现，并支持每个支持的框架和原生客户端，确保会话的任何变化（如退出登录）立即反映在你的UI中。

user.tsx
import { authClient } from "@/lib/auth-client" // 导入认证客户端
 
export function User(){
 
    const { 
        data: session, 
        isPending, //加载状态
        error, //错误对象
        refetch //重新获取会话
    } = authClient.useSession() 
 
    return (
        //...
    )
}

获取会话

如果你不想使用钩子方式，你可以使用客户端提供的getSession方法。

user.tsx
import { authClient } from "@/lib/auth-client" // 导入认证客户端
 
const { data: session, error } = await authClient.getSession()

你也可以将其与客户端数据获取库一起使用，如TanStack Query。

服务器端

服务器提供了一个session对象，你可以用它来访问会话数据。它需要将请求头对象传递给getSession方法。

示例：使用一些流行的框架

server.ts
import { auth } from "./auth"; // 你的Better Auth服务器实例路径
import { headers } from "next/headers";
 
const session = await auth.api.getSession({
    headers: await headers() // 你需要传递headers对象
})

有关更多详细信息，请查看会话管理文档。

使用插件

Better Auth的独特功能之一是插件生态系统。它允许你通过少量代码添加复杂的认证相关功能。

下面是一个使用双因素插件添加双因素认证的示例。

服务器配置

要添加插件，你需要导入插件并将其传递给auth实例的plugins选项。例如，要添加双因素认证，你可以使用以下代码：

auth.ts
import { betterAuth } from "better-auth"
import { twoFactor } from "better-auth/plugins"
 
export const auth = betterAuth({
    //...其他选项
    plugins: [ 
        twoFactor() 
    ] 
})

现在服务器上将提供双因素相关的路由和方法。

迁移数据库

添加插件后，你需要将所需的表添加到数据库中。你可以通过运行migrate命令来完成此操作，或者使用generate命令创建架构并手动处理迁移。

生成架构：

terminal
npx @better-auth/cli generate

使用migrate命令：

terminal
npx @better-auth/cli migrate

如果你更喜欢手动添加架构，可以在双因素插件文档中查看所需的架构。

客户端配置

完成服务器配置后，我们需要将插件添加到客户端。为此，你需要导入插件并将其传递给auth客户端的plugins选项。例如，要添加双因素认证，你可以使用以下代码：

auth-client.ts
import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins"; 
 
const authClient = createAuthClient({
    plugins: [ 
        twoFactorClient({ 
            twoFactorPage: "/two-factor" // 如果用户需要验证第二因素时重定向的页面
        }) 
    ] 
})

现在客户端将提供双因素相关的方法。

profile.ts
import { authClient } from "./auth-client"
 
const enableTwoFactor = async() => {
    const data = await authClient.twoFactor.enable({
        password // 需要用户密码
    }) // 这将启用双因素认证
}
 
const disableTwoFactor = async() => {
    const data = await authClient.twoFactor.disable({
        password // 需要用户密码
    }) // 这将禁用双因素认证
}
 
const signInWith2Factor = async() => {
    const data = await authClient.signIn.email({
        //...
    })
    //如果用户启用了双因素认证，它将重定向到双因素页面
}
 
const verifyTOTP = async() => {
    const data = await authClient.twoFactor.verifyTOTP({
        code: "123456", // 用户输入的代码
        /**
         * 如果设备受信任，用户在同一设备上
         * 不需要再次通过双因素认证
         */
        trustDevice: true
    })
}

下一步：查看双因素插件文档。

安装

如何在项目中使用Better Auth。

API

Better Auth API 接口文档

On this page