将 DiceBear 用作头像占位符 API
头像占位符用于替代用户尚未上传头像时显示的通用默认图标。DiceBear 不会显示灰色剪影，而是根据任意种子生成独特且确定性的 SVG 头像，因此每位用户从注册开始就能拥有一张专属图片。
为什么选择 DiceBear 作为占位符？
确定性
相同的种子始终会生成相同的头像。使用用户 ID 或邮箱作为种子，占位符在不同会话和设备之间都保持一致。
无需上传
无需存储图片，也无需审核。头像会即时生成，这对尚未拥有头像的新用户非常适用。
可自托管
运行你自己的 HTTP API 实例，以便对可用性和数据保留拥有完全控制权。
35+ 种样式
从抽象几何图形到插画角色，选择适合你产品的视觉风格。
使用 HTTP API
最简单的方法：将 DiceBear API URL 作为 <img> 标签的 src。使用稳定的标识符作为种子。数字用户 ID 就很合适。关于完整选项和速率限制详情，请参阅 HTTP API 文档。
html
<img
src="https://api.dicebear.com/10.x/initials/svg?seed=JD"
alt="用户头像"
width="48"
height="48"
/>图片错误时回退
将 DiceBear 与 onerror 处理器结合使用，以便在用户上传的照片加载失败时优雅回退：
html
<img
src="/uploads/user-123.jpg"
onerror="this.src='https://api.dicebear.com/10.x/pixel-art/svg?seed=123'; this.onerror=null;"
alt="用户头像"
/>使用用户 ID 作为种子
传入一个稳定且唯一的标识符作为种子，确保每位用户始终获得相同的占位符：
js
const userId = 'user-8f3a2c';
const avatarUrl = `https://api.dicebear.com/10.x/thumbs/svg?seed=${encodeURIComponent(userId)}`;使用 JavaScript 库
使用 JS 库进行服务端渲染，或者将 SVG 直接嵌入到你的标记中，而无需额外的 HTTP 请求。关于完整的安装和 API 详情，请参阅 JavaScript 库文档。
js
import { Avatar } from '@dicebear/core';
import thumbs from '@dicebear/styles/thumbs.json' with { type: 'json' };
function getPlaceholderAvatar(userId) {
return new Avatar(thumbs, {
seed: userId,
size: 48,
borderRadius: 50,
}).toString();
}使用 PHP 库
使用 PHP 库进行服务端渲染，而无需额外的 HTTP 请求。关于完整的安装和 API 详情，请参阅 PHP 库文档。
php
<?php
use Composer\InstalledVersions;
use DiceBear\Style;
use DiceBear\Avatar;
$basePath = InstalledVersions::getInstallPath('dicebear/styles');
$definition = json_decode(file_get_contents($basePath . '/src/thumbs.json'), true);
$style = new Style($definition);
function getPlaceholderAvatar(Style $style, string $userId): string {
return (string) new Avatar($style, [
'seed' => $userId,
'size' => 48,
'borderRadius' => 50,
]);
}使用 Python 库
使用 Python 库进行服务端渲染，而无需额外的 HTTP 请求。关于完整的安装和 API 详情，请参阅 Python 库文档。
python
import json
from importlib.resources import files
from dicebear import Avatar, Style
definition = json.loads(
files("dicebear_styles").joinpath("thumbs.json").read_text("utf-8")
)
style = Style(definition)
def get_placeholder_avatar(user_id: str) -> str:
return Avatar(style, {
"seed": user_id,
"size": 48,
"borderRadius": 50,
}).to_string()使用 Rust 库
使用 Rust 库进行服务端渲染，而无需额外的 HTTP 请求。关于完整的安装和 API 详情，请参阅 Rust 库文档。
rust
use dicebear_core::{Avatar, Error, Style};
use serde_json::json;
let style = Style::from_str(dicebear_styles::THUMBS)?;
fn placeholder_avatar(style: &Style, user_id: &str) -> Result<String, Error> {
let avatar = Avatar::new(style, json!({
"seed": user_id,
"size": 48,
"borderRadius": 50,
}))?;
Ok(avatar.to_string())
}使用 Go 库
使用 Go 库进行服务端渲染，而无需额外的 HTTP 请求。 关于完整的安装和 API 详情，请参阅 Go 库文档。
go
import (
dicebear "github.com/dicebear/dicebear-go/v10"
"github.com/dicebear/styles/v10"
)
style, _ := dicebear.NewStyle([]byte(styles.Thumbs))
func placeholderAvatar(style *dicebear.Style, userID string) (string, error) {
avatar, err := dicebear.NewAvatar(style, map[string]any{
"seed": userID,
"size": 48,
"borderRadius": 50,
})
if err != nil {
return "", err
}
return avatar.SVG(), nil
}选择样式
不同样式适用于不同的使用场景。点击某个样式即可查看所有可用选项。
首字母 适合展示用户首字母是常见做法的应用
Identicon 开发者工具、版本控制、技术平台
像素艺术 游戏、复古风或面向开发者的社区
Thumbs 友好的消费类应用和社交平台
Shapes 适用于任何场景的抽象、中性的占位符
提示：始终指定尺寸
指定 size 或 CSS 尺寸，以避免头像加载时发生布局偏移：
js
// JS 库
new Avatar(thumbs, { seed: userId, size: 48, borderRadius: 50 });php
// PHP 库
new Avatar($style, ['seed' => $userId, 'size' => 48, 'borderRadius' => 50]);python
# Python 库
Avatar(style, {"seed": user_id, "size": 48, "borderRadius": 50})rust
// Rust 库
Avatar::new(&style, json!({ "seed": user_id, "size": 48, "borderRadius": 50 }))?;go
// Go 库
dicebear.NewAvatar(style, map[string]any{"seed": userID, "size": 48, "borderRadius": 50})// HTTP API
https://api.dicebear.com/10.x/thumbs/svg?seed=user-123&size=48&borderRadius=50