安装
学习如何在你的项目中配置 Better Auth。
安装包
让我们开始将 Better Auth 添加到你的项目中:
npm install better-auth如果你使用了分离的客户端和服务器设置,请确保在项目的两个部分中都安装 Better Auth。
设置环境变量
在你的项目根目录下创建一个 .env 文件,并添加以下环境变量:
- 密钥
用于加密和哈希的密钥值。它必须至少包含 32 个字符,并且使用高熵生成。点击下方按钮生成一个。你也可以使用 openssl rand -base64 32 来生成。
BETTER_AUTH_SECRET=稍后需要轮换密钥吗?你可以使用 BETTER_AUTH_SECRETS(复数)来轮换到新密钥而不使现有数据失效。有关详细信息,请参阅 secrets 选项。
- 设置基础 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 等。
如果你未配置数据库,也可以将 Better Auth 配置为无状态模式运行。请参阅 无状态会话管理 获取更多信息。请注意,大多数插件都需要数据库。
import { betterAuth } from "better-auth";
import Database from "better-sqlite3";
export const auth = betterAuth({
database: new Database("./sqlite.db"),
})import { betterAuth } from "better-auth";
import { Pool } from "pg";
export const auth = betterAuth({
database: new Pool({
// 连接选项
}),
})
</Tab>
<Tab value="mysql">
```ts title="auth.ts"
import { betterAuth } from "better-auth";
import { createPool } from "mysql2/promise";
export const auth = betterAuth({
database: createPool({
// 连接选项
}),
})
</Tab>
</Tabs>
或者,如果你更喜欢使用 ORM,可以使用内置适配器之一。
<Tabs items={["drizzle", "prisma", "mongodb"]}>
<Tab value="drizzle">
```ts title="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"
}),
});import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
// 如果你的 Prisma 文件路径不同,可以调整导入路径
import { PrismaClient } from "@/generated/prisma/client";
const prisma = new PrismaClient();
export const auth = betterAuth({
database: prismaAdapter(prisma, {
provider: "sqlite", // 或 "mysql"、"postgresql" 等
}),
});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 工具,可帮助管理库所需的模式。
- 生成: 此命令生成 ORM 架构或 SQL 迁移文件。
如果你使用的是 Kysely,你可以直接使用 migrate 命令应用迁移。使用 generate 仅在你计划手动应用迁移时需要。
npx auth@latest generate-
迁移: 此命令直接在数据库中创建所需的表。(仅适用于内置的 Kysely 适配器)
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/* 的请求(除非你配置了不同的基础路径)。
Better Auth 支持任何具有标准 Request 和 Response 对象的后端框架,并提供流行框架的辅助函数。
import { auth } from "@/lib/auth"; // 你的 auth 文件路径
import { toNextJsHandler } from "better-auth/next-js";
export const { POST, GET } = toNextJsHandler(auth);import { auth } from "@/lib/auth"; // 你的 auth 文件路径
import { toNodeHandler } from "better-auth/node";
// 不允许自动解析请求体,手动解析
export const config = { api: { bodyParser: false } };
export default toNodeHandler(auth.handler);import { auth } from "~/utils/auth"; // auth 文件路径
export default defineEventHandler((event) => {
return auth.handler(toWebRequest(event));
});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 });
}import { auth } from '~/lib/auth.server' // 根据需要调整路径
import type { LoaderFunctionArgs, ActionFunctionArgs } from "react-router" // 或 "@remix-run/node"
export async function loader({ request }: LoaderFunctionArgs) {
return auth.handler(request)
}
export async function action({ request }: ActionFunctionArgs) {
return auth.handler(request)
}import { auth } from "~/lib/auth"; // auth 文件路径
import { toSolidStartHandler } from "better-auth/solid-start";
export const { GET, POST } = toSolidStartHandler(auth);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);import { auth } from "./auth"; // auth 文件路径
export default {
async fetch(request: Request) {
const url = new URL(request.url);
// 处理认证路由
if (url.pathname.startsWith("/api/auth")) {
return auth.handler(request);
}
// 处理其他路由
return new Response("Not found", { status: 404 });
},
};Node.js AsyncLocalStorage 支持: Better Auth 使用 AsyncLocalStorage 进行异步上下文跟踪。要在 Cloudflare Workers 中启用此功能,请在 wrangler.toml 中添加 nodejs_compat 标志:
compatibility_flags = ["nodejs_compat"]
compatibility_date = "2024-09-23"或者,如果只需要 AsyncLocalStorage 支持:
compatibility_flags = ["nodejs_als"]在下一个主要版本中,我们将默认假设支持 AsyncLocalStorage,因此此配置将成为必需。
ExpressJS v5 引入了路由匹配的重大变更,切换到 path-to-regexp@6。通配符路由 * 现在应使用新的命名语法书写,例如 /{*any},以正确捕获捕获所有模式。这确保了跨路由场景的兼容性和可预测行为。
有关详细信息,请参阅 Express v5 迁移指南。
因此,ExpressJS v5 中的实现应如下所示:
app.all('/api/auth/{*any}', toNodeHandler(auth));名称 any 是任意的,可以用你喜欢的任何标识符替换。
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 应用程序已监听端口 ${port}`);
});这也适用于任何其他 Node.js 服务器框架,如 express、fastify、hapi 等,但可能需要一些修改。参见 fastify 指南。注意不支持 CommonJS (cjs)。
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"]
// 验证请求方法
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 正在运行于 ${app.server?.hostname}:${app.server?.port}`
);import { auth } from '@/lib/auth'
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/api/auth/$')({
server: {
handlers: {
GET: async ({ request }:{ request: Request }) => {
return await auth.handler(request)
},
POST: async ({ request }:{ request: Request }) => {
return await auth.handler(request)
},
},
},
})当调用需要设置 Cookie 的函数(如 signInEmail 或 signUpEmail)时,你需要处理 TanStack Start 的 Cookie 设置。Better Auth 提供了 tanstackStartCookies 插件来自动处理此问题。
对于 React(TanStack Start with React):
import { betterAuth } from "better-auth";
import { tanstackStartCookies } from "better-auth/tanstack-start";
export const auth = betterAuth({
//...your config
plugins: [tanstackStartCookies()] // 确保这是数组中的最后一个插件
})对于 Solid.js(TanStack Start with Solid):
import { betterAuth } from "better-auth";
import { tanstackStartCookies } from "better-auth/tanstack-start/solid";
export const auth = betterAuth({
//...your config
plugins: [tanstackStartCookies()] // 确保这是数组中的最后一个插件
})现在,当调用设置 Cookie 的函数时,它们将自动使用 TanStack Start 的 Cookie 处理系统进行设置。
import { auth } from '@/lib/server/auth'; // auth 文件路径
const handler = auth.handler;
export { handler as GET, handler as POST };创建客户端实例
客户端库帮助你与认证服务器进行交互。Better Auth 为所有流行的 Web 框架提供了客户端,包括原生 JavaScript。
- 从对应框架的包中导入
createAuthClient(例如,在 React 中导入 "better-auth/react")。 - 调用该函数来创建你的客户端。
- 传入你的认证服务器的基础 URL。(如果认证服务器与客户端运行在同一个域上,可以跳过此步骤。)
如果你使用的不是 /api/auth 的基础路径,请确保传入完整的 URL,包括路径。(例如
http://localhost:3000/custom-path/auth)
import { createAuthClient } from "better-auth/client"
export const authClient = createAuthClient({
/** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
baseURL: "http://localhost:3000"
})import { createAuthClient } from "better-auth/react"
export const authClient = createAuthClient({
/** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
baseURL: "http://localhost:3000"
})import { createAuthClient } from "better-auth/vue"
export const authClient = createAuthClient({
/** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
baseURL: "http://localhost:3000"
})import { createAuthClient } from "better-auth/svelte"
export const authClient = createAuthClient({
/** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
baseURL: "http://localhost:3000"
})import { createAuthClient } from "better-auth/solid"
export const authClient = createAuthClient({
/** 服务器的基础 URL(可选,如果使用相同域名则不需要) */
baseURL: "http://localhost:3000"
})提示:如果你只想导出特定方法,可以这样做:
export const { signIn, signUp, useSession } = createAuthClient()