使用Payload Better Auth创建你的第一个插件：生日验证功能开发指南

2025-06-19 23:18:05作者：董灵辛Dennis

Payload Better Auth是一个强大的身份验证解决方案，它允许开发者通过插件机制扩展核心功能。本文将带你从零开始开发一个生日验证插件，通过这个实战案例，你将掌握Payload Better Auth插件开发的核心概念和流程。

前置条件

在开始之前，请确保你已经完成了Payload Better Auth的基础配置工作。本教程假设你已经搭建好了基本的开发环境，并准备好创建你的第一个插件。

第一步：规划插件功能

任何插件开发的第一步都是明确功能需求。在本案例中，我们将开发一个生日插件，主要功能包括：

记录用户的出生日期
验证用户年龄是否超过5岁
提供前后端一致的验证逻辑

第二步：创建服务器端插件

Payload Better Auth的插件采用前后端分离架构，由服务器插件和客户端插件组成。服务器插件负责核心业务逻辑和数据处理，是插件系统的基石。

基础结构搭建

首先创建一个名为birthday-plugin的文件夹，并在其中创建index.ts文件：

birthday-plugin/
└── index.ts

在index.ts中，我们导出一个函数来定义我们的服务器插件：

import { createAuthClient } from "better-auth/client";
import type { BetterAuthPlugin } from "better-auth";

export const birthdayPlugin = () =>
  ({
    id: "birthdayPlugin",
  } satisfies BetterAuthPlugin);

虽然这只是一个空壳，但你已经成功创建了第一个插件的基础结构！

定义数据模型

为了存储用户的生日信息，我们需要在用户模型上扩展字段。通过定义schema，Payload Better Auth的CLI工具可以自动生成数据库迁移脚本。

export const birthdayPlugin = () =>
  ({
    id: "birthdayPlugin",
    schema: {
      user: {
        fields: {
          birthday: {
            type: "date",       // 字段类型，支持string/number/boolean/date
            required: true,     // 是否必填，默认为false
            unique: false,      // 是否唯一，默认为false
            reference: null     // 关联字段，默认为null
          },
        },
      },
    },
  } satisfies BetterAuthPlugin);

实现业务逻辑

现在，我们来实现核心功能：验证用户年龄是否超过5岁。这里我们使用**钩子(Hooks)**机制，在特定操作前后执行自定义逻辑。

import { APIError } from "better-auth/api";
import { createAuthMiddleware } from "better-auth/plugins";

export const birthdayPlugin = () => ({
    // ...之前的配置
    
    hooks: {
      before: [
        {
          matcher: (context) => context.path.startsWith("/sign-up/email"),
          handler: createAuthMiddleware(async (ctx) => {
            const { birthday } = ctx.body;
            
            // 类型验证
            if(!birthday instanceof Date) {
              throw new APIError("BAD_REQUEST", { 
                message: "生日必须是有效的日期格式" 
              });
            }

            // 年龄验证
            const today = new Date();
            const fiveYearsAgo = new Date(today.setFullYear(today.getFullYear() - 5));

            if(birthday >= fiveYearsAgo) {
              throw new APIError("BAD_REQUEST", { 
                message: "用户必须年满5岁以上" 
              });
            }

            return { context: ctx };
          }),
        },
      ],
    },
} satisfies BetterAuthPlugin)

这段代码实现了：

拦截所有注册请求
验证生日字段是否为有效日期
计算用户年龄是否超过5岁
根据验证结果返回相应错误或继续流程

第三步：创建客户端插件

客户端插件主要负责提供类型安全和便捷的前端API。对于生日插件来说，客户端逻辑相对简单。

创建client.ts文件：

birthday-plugin/
├── index.ts
└── client.ts

添加以下内容：

import { BetterAuthClientPlugin } from "better-auth";
import type { birthdayPlugin } from "./index";

type BirthdayPlugin = typeof birthdayPlugin;

export const birthdayClientPlugin = () => {
  return {
    id: "birthdayPlugin",
    $InferServerPlugin: {} as ReturnType<BirthdayPlugin>,
  } satisfies BetterAuthClientPlugin;
};

这个客户端插件主要作用是：

保持与服务器插件一致的ID
自动推断服务器插件定义的类型
为前端提供类型安全的API

第四步：集成插件

完成插件开发后，需要将其集成到你的应用中。

服务器端集成

import { betterAuth } from "better-auth";
import { birthdayPlugin } from "./birthday-plugin";
 
export const auth = betterAuth({
    plugins: [
      birthdayPlugin(),
    ]
});

客户端集成

import { createAuthClient } from "better-auth/client";
import { birthdayClientPlugin } from "./birthday-plugin/client";
 
const authClient = createAuthClient({
    plugins: [
      birthdayClientPlugin()
    ]
});