基本用法

Better Auth 提供内置的认证支持：

邮箱和密码
社交提供商（Google、GitHub、Apple 等）

邮箱 & 密码

启用邮箱和密码认证：

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

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

始终在客户端调用客户端方法。不要从服务器调用它们。

服务器端认证

要在服务器端认证用户，可以使用 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 支持多种社交提供商，包括 Google、GitHub、Apple、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，在 onSuccess 时进行重定向

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" // import the auth client

export function User(){

    const { 
        data: session, 
        isPending, //loading state
        error, //error object
        refetch //refetch the session
    } = 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() // 需传入请求头对象
})

更多详情请查看会话管理文档

使用插件

Better Auth 的一大特色是拥有插件生态系统，能够通过少量代码实现复杂的认证功能。

下面示例演示如何使用两步验证插件添加双因素认证。

服务器配置

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

auth.ts

import { betterAuth } from "better-auth"
import { twoFactor } from "better-auth/plugins"

export const auth = betterAuth({
    //...rest of the options
    plugins: [ 
        twoFactor() 
    ] 
})

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

迁移数据库

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

生成架构：

terminal

npx auth generate

使用 migrate 命令：

terminal

npx auth migrate

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

客户端配置

完成服务器配置后，需要将插件添加到客户端。为此，需要导入插件并将其传入认证客户端的 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" // the page to redirect if a user needs to verify 2nd factor
        }) 
    ] 
})

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

profile.ts

import { authClient } from "./auth-client"

const enableTwoFactor = async() => {
    const data = await authClient.twoFactor.enable({
        password // the user password is required
    }) // this will enable two factor
}

const disableTwoFactor = async() => {
    const data = await authClient.twoFactor.disable({
        password // the user password is required
    }) // this will disable two factor
}

const signInWith2Factor = async() => {
    const data = await authClient.signIn.email({
        //...
    })
    //if the user has two factor enabled, it will redirect to the two factor page
}

const verifyTOTP = async() => {
    const data = await authClient.twoFactor.verifyTOTP({
        code: "123456", // the code entered by the user 
        /**
         * If the device is trusted, the user won't
         * need to pass 2FA again on the same device
         */
        trustDevice: true
    })
}

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

On this page