BETTER-AUTH.

用户名

用户名插件

用户名插件是一个轻量级插件，为电子邮件和密码认证器添加了用户名支持。这样用户可以使用用户名而不是电子邮件进行登录。

安装

将插件添加到服务器

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

export const auth = betterAuth({
    emailAndPassword: { 
        enabled: true, 
    }, 
    plugins: [ 
        username() 
    ] 
})

运行数据库迁移

运行迁移或生成架构，以向数据库添加所需的字段和表。

npx auth migrate
npx auth generate

更多详情请参见 Schema 部分，手动添加字段。

添加客户端插件

auth-client.ts
import { createAuthClient } from "better-auth/client"
import { usernameClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
    plugins: [ 
        usernameClient() 
    ] 
})

使用方法

注册

要使用用户名注册用户，可以使用客户端提供的现有 signUp.email 函数。
signUp 函数接受一个新增的 username 属性。

POST/sign-up/email
const { data, error } = await authClient.signUp.email({    email: "email@domain.com", // required    name: "Test User", // required    password: "password1234", // required    username: "test",    displayUsername: "Test User123",});
Parameters
emailstringrequired

用户的电子邮件。

namestringrequired

用户的名字。

passwordstringrequired

用户的密码。

usernamestring

用户的用户名。

displayUsernamestring

用户的可选显示用户名。

如果只提供了 username，则 displayUsername 会被设为该用户名的预标准化版本。更多详情请参见 用户名标准化 和 显示用户名标准化 部分。

登录

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

POST/sign-in/username
const { data, error } = await authClient.signIn.username({    username: "test", // required    password: "password1234", // required});
Parameters
usernamestringrequired

用户名。

passwordstringrequired

密码。

更新用户名

要更新用户的用户名，可以使用客户端提供的 updateUser 函数。

POST/update-user
const { data, error } = await authClient.updateUser({    username: "new-username",});
Parameters
usernamestring

要更新的用户名。

检查用户名是否可用

要检查用户名是否可用，可以使用客户端提供的 isUsernameAvailable 函数。

POST/is-username-available
const { data: response, error } = await authClient.isUsernameAvailable({    username: "new-username", // required});if(response?.available) {    console.log("用户名可用");} else {    console.log("用户名不可用");}
Parameters
usernamestringrequired

要检查的用户名。

选项

最小用户名长度

用户名的最小长度。默认为 3。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    plugins: [
        username({
            minUsernameLength: 5
        })
    ]
})

最大用户名长度

用户名的最大长度。默认为 30。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    plugins: [
        username({
            maxUsernameLength: 100
        })
    ]
})

用户名验证器

一个验证用户名的函数。如果用户名无效，该函数应返回 false。默认情况下，用户名只允许包含字母数字字符、下划线和点。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    plugins: [
        username({
            usernameValidator: (username) => {
                if (username === "admin") {
                    return false
                }
                return true
            }
        })
    ]
})

显示用户名验证器

一个验证显示用户名的函数。如果显示用户名无效，该函数应返回 false。默认情况下，对显示用户名不进行验证。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    plugins: [
        username({
            displayUsernameValidator: (displayUsername) => {
                // 只允许字母数字字符、下划线和连字符
                return /^[a-zA-Z0-9_-]+$/.test(displayUsername)
            }
        })
    ]
})

用户名标准化

一个用于标准化用户名的函数，或者设置为 false 以禁用标准化。

默认情况下，用户名被标准化为小写，比如 "TestUser" 和 "testuser" 被视为相同的用户名。username 字段包含标准化（小写）的用户名，而 displayUsername 保持原始的用户名。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    plugins: [
        username({
            usernameNormalization: (username) => {
                return username.toLowerCase()
                    .replaceAll("0", "o")
                    .replaceAll("3", "e")
                    .replaceAll("4", "a");
            }
        })
    ]
})

显示用户名标准化

一个用于标准化显示用户名的函数，或设置为 false 禁用标准化。

默认情况下，显示用户名不进行标准化。当仅提供 username 进行注册或更新时，displayUsername 会设为原始的 username（标准化之前）。你也可以显式地设置 displayUsername，该值会被原样保留。如需自定义标准化，请提供一个接受显示用户名为输入并返回标准化结果的函数。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    plugins: [
        username({
            displayUsernameNormalization: (displayUsername) => displayUsername.toLowerCase(),
        })
    ]
})

验证顺序

默认情况下，用户名和显示用户名在标准化之前进行验证。你可以通过设置 validationOrder 为 post-normalization 来改变此行为。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    plugins: [
        username({
            validationOrder: {
                username: "post-normalization",
                displayUsername: "post-normalization",
            }
        })
    ]
})

禁用“用户名是否可用”接口

默认情况下，插件提供了 /is-username-available 接口用于检查用户名是否可用。你可以通过在 better-auth 配置中提供 disabledPaths 选项禁用此接口。这对于防止用户名被枚举很有用。

auth.ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
    },
    disabledPaths: ["/is-username-available"],
    plugins: [
        username()
    ]
})

架构

该插件需要在用户表中添加 2 个字段：

Table
字段
类型
键
描述
username
string
—
用户的用户名
displayUsername
string
—
非标准化的用户名
在 GitHub 上编辑

本页目录

安装
将插件添加到服务器
运行数据库迁移
添加客户端插件
使用方法
注册
登录
更新用户名
检查用户名是否可用
选项
最小用户名长度
最大用户名长度
用户名验证器
显示用户名验证器
用户名标准化
显示用户名标准化
验证顺序
禁用“用户名是否可用”接口
架构