用户名

用户名插件是一个轻量级插件，为邮箱和密码认证器添加了用户名支持。这使得用户可以使用用户名而非邮箱进行登录和注册。

安装

在服务端添加插件

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 属性。

auth-client.ts
const data = await authClient.signUp.email({
    email: "email@domain.com",
    name: "Test User",
    password: "password1234",
    username: "test"
})

您也可以提供 displayUsername（显示用户名）

auth-client.ts
const data = await authClient.signUp.email({
    email: "email@domain.com",
    name: "Test User",
    password: "password1234",
    username: "test",
    displayUsername: "Test User123"
})

如果只提供了 username，displayUsername 将被设置为 username 的预规范化版本。更多详情请参阅用户名规范化和显示用户名规范化部分。

用户登录

要通过用户名登录用户，您可以使用客户端提供的 signIn.username 函数。signIn 函数接受一个包含以下属性的对象：

  • username: 用户的用户名
  • password: 用户的密码
auth-client.ts
const data = await authClient.signIn.username({
    username: "test",
    password: "password1234",
})

更新用户名

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

auth-client.ts
const data = await authClient.updateUser({
    username: "new-username"
})

检查用户名是否可用

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

auth-client.ts
const response = await authClient.isUsernameAvailable({
    username: "new-username"
});

if(response.data?.available) {
    console.log("用户名可用");
} else {
    console.log("用户名不可用");
}

选项

最小用户名长度

用户名的最小长度。默认值为 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) => {
                // 仅允许字母数字字符、下划线和连字符
                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",
            }
        })
    ]
})

数据表结构

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

字段名称类型Key描述
usernamestring-用户的用户名
displayUsernamestring-用户的非规范化用户名
Edit on GitHub

Previous Page

双重认证

Next Page

匿名

On this page