邮件

邮件是Better Auth 的关键组成部分，无论用户使用何种认证方式，都需要邮件功能。Better Auth 默认提供了邮箱和密码认证，以及许多实用工具来帮助你管理邮件验证、密码重置等功能。

邮件验证

邮件验证是一项安全功能，确保用户提供有效的电子邮件地址。它通过确认电子邮件地址属于用户来帮助防止垃圾邮件和滥用。

为你的应用添加邮件验证

要启用邮件验证，你需要传递一个发送验证邮件的函数。

  • sendVerificationEmail：当邮件验证开始时触发此函数。它接受一个包含以下属性的数据对象：
    • user：包含电子邮件地址的用户对象。
    • url：用户必须点击以验证其电子邮件的验证 URL。
    • token：用于完成邮件验证的验证令牌，在实现自定义验证 URL 时使用。

以及作为第二个参数的 request 对象。

auth.ts
import { betterAuth } from 'better-auth';
import { sendEmail } from './email'; // 你的邮件发送函数
 
export const auth = betterAuth({
    emailVerification: {
        sendVerificationEmail: async ({ user, url, token }, request) => {
            await sendEmail({
                to: user.email,
                subject: '验证你的电子邮件地址',
                text: `点击链接验证你的电子邮件：${url}`
            })
        }
    }
})

触发邮件验证

你可以通过以下几种方式触发邮件验证：

1. 在注册时

要在注册时自动发送验证邮件，将 emailVerification.sendOnSignUp 设置为 true。

auth.ts
import { betterAuth } from 'better-auth';
 
export const auth = betterAuth({
    emailVerification: {
        sendOnSignUp: true
    }
})

这会在用户注册时发送验证邮件。对于社交登录，邮件验证状态从 SSO 读取。

启用 sendOnSignUp 后，当用户使用未声明邮件已验证的 SSO 登录时，Better Auth 将发送验证邮件，但即使启用了 requireEmailVerification，验证也不是登录所必需的。

2. 要求邮件验证

如果你启用要求邮件验证，用户必须在登录前验证其电子邮件。每次用户尝试登录时，都会调用 sendVerificationEmail。

这仅在你实现了 sendVerificationEmail 且用户尝试使用邮箱和密码登录时才有效。

auth.ts
export const auth = betterAuth({
    emailAndPassword: {
        requireEmailVerification: true
    }
})

如果用户尝试在未验证电子邮件的情况下登录，你可以处理错误并向用户显示消息。

auth-client.ts
await authClient.signIn.email({
    email: "email@example.com",
    password: "password"
}, {
    onError: (ctx) => {
        // 处理错误
        if(ctx.error.status === 403) {
            alert("请验证你的电子邮件地址")
        }
        // 你也可以显示原始错误消息
        alert(ctx.error.message)
    }
})

3. 手动触发

你也可以通过调用 sendVerificationEmail 手动触发邮件验证。

await authClient.sendVerificationEmail({
    email: "user@email.com",
    callbackURL: "/" // 验证后的重定向 URL
})

验证电子邮件

如果用户点击提供的验证 URL，他们的电子邮件将自动验证，并且他们将被重定向到 callbackURL。

对于手动验证，你可以向用户发送带有 token 的自定义链接，并调用 verifyEmail 函数。

authClient.verifyEmail({
    query: {
        token: "" // 在这里传递令牌
    }
})

验证后自动登录

要在用户成功验证电子邮件后自动登录，将 autoSignInAfterVerification 选项设置为 true：

const auth = betterAuth({
    //...你的其他选项
    emailVerification: {
        autoSignInAfterVerification: true
    }
})

密码重置邮件

密码重置允许用户在忘记密码时重置密码。Better Auth 提供了一种简单的方法来实现密码重置功能。

你可以通过传递一个发送带有链接的密码重置邮件的函数来启用密码重置。

auth.ts
import { betterAuth } from 'better-auth';
import { sendEmail } from './email'; // 你的邮件发送函数
 
export const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
        sendResetPassword: async ({ user, url, token }, request) => {
            await sendEmail({
                to: user.email,
                subject: '重置你的密码',
                text: `点击链接重置你的密码：${url}`
            })
        }
    }
})

查看邮箱和密码指南，了解更多关于如何在你的应用中实现密码重置的详细信息。

数据库

了解如何在Better Auth中使用数据库

钩子

Better Auth 钩子让你可以hook生命周期并执行自定义逻辑。它们提供了一种自定义 Better Auth 行为的方式，而无需编写完整的插件。

On this page