用户名

用户名插件是一个轻量级插件，它为电子邮件和密码认证器添加用户名支持。这允许用户使用他们的用户名而不是电子邮件进行登录和注册。

安装

将插件添加到服务器

auth.ts

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

export const auth = betterAuth({
    plugins: [ 
        username() 
    ] 
})

迁移数据库

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

npx @better-auth/cli migrate

npx @better-auth/cli generate

请参阅架构部分，手动添加字段。

添加客户端插件

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", // required
    displayUsername: "Test User123",
});

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

Prop	Description	Type
`email`	用户的电子邮件。	`string`
`name`	用户的名称。	`string`
`password`	用户的密码。	`string`
`username`	用户的用户名。	`string`
`displayUsername?`	用户的可选显示用户名。	`string`

POST

/sign-up/email

const data = await auth.api.signUpEmail({
    body: {
        email: "email@domain.com", // required
        name: "Test User", // required
        password: "password1234", // required
        username: "test", // required
        displayUsername: "Test User123",
    },
});

const data = await auth.api.signUpEmail({    body: {        email: "email@domain.com", // required        name: "Test User", // required        password: "password1234", // required        username: "test", // required        displayUsername: "Test User123",    },});

Prop	Description	Type
`email`	用户的电子邮件。	`string`
`name`	用户的名称。	`string`
`password`	用户的密码。	`string`
`username`	用户的用户名。	`string`
`displayUsername?`	用户的可选显示用户名。	`string`

如果仅提供 username，则 displayUsername 将设置为 username 的预规范化版本。您可以参阅用户名规范化和显示用户名规范化部分以获取更多细节。

Prop	Description	Type
`username`	用户的用户名。	`string`
`password`	用户的密码。	`string`

Prop	Description	Type
`username`	用户的用户名。	`string`
`password`	用户的密码。	`string`

更新用户名

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

POST

/update-user

const { data, error } = await authClient.updateUser({
    username: "new-username",
});

const { data, error } = await authClient.updateUser({    username: "new-username",});

Prop	Description	Type
`username?`	要更新的用户名。	`string`

POST

/update-user

const data = await auth.api.updateUser({
    body: {
        username: "new-username",
    },
});

const data = await auth.api.updateUser({    body: {        username: "new-username",    },});

Prop	Description	Type
`username?`	要更新的用户名。	`string`

检查用户名是否可用

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

POST

/is-username-available

const { data: response, error } = await authClient.isUsernameAvailable({
    username: "new-username", // required
});

if(response?.available) {
    console.log("Username is available");
} else {
    console.log("Username is not available");
}

const { data: response, error } = await authClient.isUsernameAvailable({    username: "new-username", // required});if(response?.available) {    console.log("Username is available");} else {    console.log("Username is not available");}

Prop	Description	Type
`username`	要检查的用户名。	`string`

POST

/is-username-available

const response = await auth.api.isUsernameAvailable({
    body: {
        username: "new-username", // required
    },
});

if(response?.available) {
    console.log("Username is available");
} else {
    console.log("Username is not available");
}

const response = await auth.api.isUsernameAvailable({    body: {        username: "new-username", // required    },});if(response?.available) {    console.log("Username is available");} else {    console.log("Username is not available");}

Prop	Description	Type
`username`	要检查的用户名。	`string`

选项

最小用户名长度

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

auth.ts

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

const auth = betterAuth({
    plugins: [
        username({
            minUsernameLength: 5
        })
    ]
})

最大用户名长度

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

auth.ts

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

const auth = betterAuth({
    plugins: [
        username({
            maxUsernameLength: 100
        })
    ]
})

用户名验证器

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

auth.ts

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

const auth = betterAuth({
    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({
    plugins: [
        username({
            displayUsernameValidator: (displayUsername) => {
                // Allow only alphanumeric characters, underscores, and hyphens
                return /^[a-zA-Z0-9_-]+$/.test(displayUsername)
            }
        })
    ]
})

用户名规范化

一个规范化用户名的函数，或者如果您想禁用规范化，则为 false。

默认情况下，用户名被规范化成小写，因此例如 "TestUser" 和 "testuser" 被视为相同的用户名。username 字段将包含规范化的（小写）用户名，而 displayUsername 将包含原始 username。

auth.ts

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

const auth = betterAuth({
    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({
    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({
    plugins: [
        username({
            validationOrder: {
                username: "post-normalization",
                displayUsername: "post-normalization",
            }
        })
    ]
})

架构

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

Field Name	Type	Key	Description
username	string	-	用户的用户名
displayUsername	string	-	用户的非规范化用户名

开始使用

概念

认证

数据库

集成

插件

指南

参考

On this page