DiceBear Avataaars 预设（Presets）实战指南：11 套现成配置、代码生成与 Playground 调参

• UI组件
• 后端

DiceBear 官方文档为每个主流样式都准备了「预设（Presets）」画廊，其中 Avataaars 样式共内置 11 套可直接使用的渲染选项组合。本文以 Avataaars 预设页 为骨架，结合仓库中预设数据文件、画廊组件与校验脚本的源码实现，完整讲解预设的本质、11 套预设的每一组选项、如何把它们复制到 JavaScript / PHP / Python / Rust / Go / Dart / C# 与 HTTP API / CLI 中，以及如何在 Playground 里继续调参。

读完本文，你将能：读懂预设 JSON 中每个选项的含义与取值约束；把任意一套预设变成自己项目里可运行的头像生成代码；掌握「预设固定了哪些选项、哪些选项仍随 seed 变化」的判断方法，以及仓库如何通过自动化校验保证预设永不过期。

一、预设是什么：一袋普通的渲染选项

官方对预设的定义非常朴素：预设就是一组普通的渲染选项（render options）。它既不是新的配置格式，也不是样式定义的子集，更不会让任何核心库感知到「预设」这个概念的存在。在 presets.ts 的类型定义 中可以看到预设的数据结构：

export type StylePreset = { /** Stable, kebab-case. Used in the `?preset=` playground link. */ id: string; name: string; /** One line, shown next to the avatars. */ summary: string; /** The longer rationale, shown when the card is expanded. */ description: string; options: Record<string, unknown>; };

其中options就是一个普通的键值对对象，键是样式支持的选项名（如backgroundColor、hairColor、accessoriesProbability），值是颜色数组、枚举数组或数字。因此它天然具备三个特性：

• 在所有官方库中开箱即用：预设的选项原样传给new Avatar(style, options)即可，七个语言核心（JS / PHP / Python / Rust / Go / Dart / C#）都不需要知道预设的存在；
• 可以作为 HTTP API 的查询参数：选项数组以逗号分隔拼进 URL（详见下文第五节），预设文件同样适用；
• 不强制你使用它：预设只固定一部分选项，其余选项继续随 seed 变化，因此画廊中每一行都会标注「这套预设还能生成多少个不同的头像」。

文档页面的文案也强调了这一点：「A preset sets a few of Avataaars' options and leaves every other one to you. Read its code or open it in the Playground and keep tuning.」——预设的作用是给你一个高质量的起点，而不是终结调参。

二、预设数据从哪来：JSON 文件 + 懒加载画廊

Avataaars 的全部预设存放在 apps/docs/.vitepress/theme/presets/avataaars.json，一个样式对应一个 JSON 文件。加载逻辑在 presets.ts 中，通过import.meta.glob('../presets/*.json')自动收集：

const loaders = new Map<string, () => Promise<PresetFile>>(); for (const [path, load] of Object.entries( import.meta.glob<PresetFile>('../presets/*.json', { import: 'default' }), )) { loaders.set(path.slice(path.lastIndexOf('/') + 1, -'.json'.length), load); }

这段源码透露了两个工程细节：

1. 懒加载是按需的：源码注释说明，如果把所有样式文件急切内联，55 个文件会合并成一个 214 KB 的大 chunk，每个样式页都会拉下它；改为懒加载后，Vite 为每个样式单独产出 chunk，页面只取自己需要的那个；
2. 没有预设是正常状态：loadStylePresets在没有匹配文件时返回空数组而不是抛错，因为目前大多数样式还没有预设。

画廊页面的渲染组件是 SitePresetsPage.vue，它的布局规则值得注意：

• 页面头部：标题由预设数量自动生成（11 套时显示 "Eleven Avataaars starting points"），副标题点明预设的用途；
• 侧栏：从预设列表中按步长抽取 4 套（featured），在同一个 seed 下渲染，让颜色形成对比；
• 主体列表：每一行（SitePresetRow）复用完全相同的一组 seed（来自getPreviewRowSeeds的前 3 个），这样所有预设可以在同一批 seed 下横向对比，而不是各用各的随机种子；
• 两个出口：每行提供「Code」按钮（打开对话框查看生成代码）和「Playground」按钮（跳转/playground/?style=avataaars&preset=<id>）。

三、Avataaars 样式速览：这 11 套预设固定了什么

Avataaars 是「卡通半身角色」风格，拥有大量发型、服装、配饰与表情变体（见 样式主页）。预设所操作的选项主要分三类：

• 颜色组（color groups）：backgroundColor、skinColor、hairColor、facialHairColor、clothesColor、hatColor、accessoriesColor，值为不带#的十六进制颜色数组，渲染时由 seed 从中选取；
• 变体枚举（variant enums）：eyesVariant、mouthVariant、topVariant等，值为组件变体名数组，用于锁定或收窄可出现的样式范围；
• 概率选项（probability options）：accessoriesProbability、facialHairProbability等，取值 0～100。

下表是 Avataaars 全部 11 套预设的一览：

其中sepia、greyscale、duotone、muted四套共用同一份变体锁定清单（详见第四节），差别只在于颜色方案；其余预设则只动少量选项，最大限度保留样式的多样性。

四、11 套预设逐套详解

4.1 共用变体清单：四套「调色板预设」锁定同一组变体

sepia、greyscale、duotone、muted四套预设都把眼睛、嘴和头发变体锁定到同一份全量清单（来自 avataaars.json）：

"eyesVariant": ["closed", "default", "eyeRoll", "happy", "side", "squint", "surprised", "wink", "winkWacky", "xDizzy"], "mouthVariant": ["default", "disbelief", "eating", "grimace", "sad", "serious", "twinkle"], "topVariant": ["bigHair", "bob", "bun", "curly", "curvy", "dreads", "dreads01", "dreads02", "frizzle", "fro", "hat", "hijab", "longButNotTooLong", "miaWallace", "shaggy", "shaggyMullet", "shavedSides", "shortCurly", "shortFlat", "shortRound", "shortWaved", "sides", "straight01", "straight02", "straightAndStrand", "theCaesar", "theCaesarAndSidePart", "turban", "winterHat02", "winterHat03", "winterHat04", "winterHat1"]

表面上看这份清单包含了大多数变体，等于「没锁」。但它的真实意图是排除少数特殊变体：例如带印刷图案/标志的发型（top中需要单独 print 色的款式）、哭红的眼睛、以及露出粉色舌头的嘴型。这些变体无法被任何颜色组覆盖，混入统一调色板会破坏整体感。预设描述里明确写道：「The tops with printed color come out, along with the crying eyes and the mouths that open onto a pink tongue, since no option reaches any of those.」

4.2 Bare：关掉两个可选组件

{ "accessoriesProbability": 0, "facialHairProbability": 0 }

Avataaars 默认情况下，约每 10 个头像中就有 1 个会同时出现眼镜和胡须（预设描述原话：「Both appear on one avatar in ten by default」）。Bare 把两个可选组件的概率都设为 0，其价值不在于让头像变朴素，而在于让整组头像更加整齐一致——例如在团队头像墙或表格里，避免少数头像突然多出眼镜和胡子。

4.3 Sepia：六组颜色统一到一条棕色渐变

sepia把六个颜色组全部收拢到暖棕色调色板，形成老照片式的统一观感：

{ "backgroundColor": ["ede2ce"], "skinColor": ["d9bd94", "c4a377", "a8865a", "8a6a43", "e3cdb0"], "hairColor": ["3a2916", "4a3018", "5c4223", "7d6038", "a08256"], "facialHairColor": ["3a2916", "4a3018", "5c4223"], "clothesColor": ["8a6a3c", "6d5031", "a88b60", "5a4227"], "hatColor": ["6d5031", "8a6a3c"], "accessoriesColor": ["4a3018", "7d6038"] }

注意颜色值一律不带#。皮肤 5 个色阶、头发 5 个色阶、衣服 4 个色阶，同一 ramp 内仍有明暗差异，配合 4.1 的变体清单，同一套预设依然能产出可观数量的不同头像。

4.4 Greyscale：完全去色的灰阶版

{ "backgroundColor": ["ececee"], "skinColor": ["e4e4e7", "c1c1c7", "a1a1aa", "76767e", "d4d4d8"], "hairColor": ["18181b", "3f3f46", "52525b", "71717a", "a1a1aa"], "facialHairColor": ["18181b", "3f3f46", "52525b"], "clothesColor": ["3f3f46", "52525b", "71717a", "27272a"], "hatColor": ["27272a", "52525b"], "accessoriesColor": ["18181b", "71717a"] }

适用场景在预设描述中写得很清楚：打印样式表、禁用（disabled）状态，或任何颜色会携带不该有的语义的场合。Avataaars 依靠形状而非颜色来区分层次，所以灰色组依然可读。排除变体与 Sepia 完全一致。

4.5 Duotone：单一蓝色的三个明度阶

{ "backgroundColor": ["e6ecef"], "skinColor": ["9ec9e8"], "hairColor": ["1d3d52"], "facialHairColor": ["1d3d52"], "clothesColor": ["37718e"], "hatColor": ["1d3d52"], "accessoriesColor": ["1d3d52"] }

浅肤色、中蓝衣服、深蓝头发，全部同属一个色相，只通过明度区分层次。预设描述点出了它的效果：「Every avatar in a set shares them, so only the haircut and the expression separate two of them.」——同一套 Duotone 下的两个头像，差异只剩发型和表情。

4.6 Muted：只动衣服的土色调

{ "clothesColor": [ "6b705c", "a5a58d", "b98b73", "7c9082", "8e9aaf", "9c6b58", "8a7f6d" ] }

这套预设只把衣服颜色换成一串低饱和土色（同时沿用 4.1 的变体锁定，把会破坏安静调色板的印刷表情排除掉），皮肤、头发、背景全部保持原样随 seed 变化。预设描述解释：Avataaars 默认给衣服配了 14 种颜色，其中大部分是高饱和的，在同时展示 30 个头像的表格里会显得喧闹，Muted 让衣服「静下来」。

4.7 Electric：衣服颜色超出样式自带范围

{ "clothesColor": ["ff2e88", "00e5ff", "7cff00", "ffe600", "ff6a00", "b400ff"] }

与 Muted 相反，Electric 只动衣服，而且用的是样式自身没配过的荧光色。设计理由在描述中：「Only the clothes move, because loud clothes under loud hair cancel each other out.」——既然发型已经够抢眼，那就让衣服更抢眼，而不是两边一起「响」。

4.8 Pastel Wall：柔和底色

{ "backgroundColor": ["b6e3f4", "c0aede", "d1d4f9", "ffd5dc", "ffdfbf", "d9f2d9"] }

Avataaars 样式默认不画背景。Pastel Wall 用 6 个淡色给每个头像一个「瓷砖」，且不与衣服颜色打架。

4.9 Bold Pop：饱和底色

{ "backgroundColor": ["ff2e63", "00c2a8", "ffb300", "3d5afe", "8e24aa", "00e676"] }

高饱和背景用于需要活泼观感的场景。预设描述特别提到：该样式要求衣服、头发和皮肤与背景存在色差（对比约束），因此它会自动绕着背景色选择前景，而不是与背景冲突——这正是 DiceBear 颜色约束系统的体现。

4.10 Night Shift：深色界面专用

{ "backgroundColor": ["16161a"], "clothesColor": ["e6e6e6", "b1e2ff", "a7ffc4", "ffffb1", "ffafb9"] }

为深色界面设计：背景近黑，衣服换成浅色系，因为样式自带的炭黑、藏青衬衫在深色瓷砖上会「消失」。同时把背景固定为单一深色，保证整组头像背景统一。

4.11 Sunrise：渐变背景演示

{ "backgroundColor": ["ffd5a8", "ff9db4"], "backgroundColorFill": "linear", "backgroundColorAngle": 45 }

这套预设是渐变背景选项的活教程：两个背景色、线性填充（linear）、固定角度（45°）。两个色标都保持浅色，让深色头发始终保有清晰的边缘。

4.12 Full Cast：人人都有眼镜和胡须

{ "accessoriesProbability": 100, "facialHairProbability": 100 }

与 Bare 正好相反，把两个可选组件的概率都拉到 100。预设描述给出了背后的数据：Avataaars 自带 7 款眼镜和 5 种胡须，而默认随机下「十个 seed 里有九个」都抽不到它们。Full Cast 让这些稀有配件全面登场。

五、把预设变成可运行的代码：九种语言/通道的生成逻辑

画廊页面每一行的「Code」按钮会打开 StylePresetDialog.vue，内部由 StyleOptionsCodePanel.vue 渲染出 9 个页签：HTTP API、JavaScript、PHP、Python、Rust、Go、Dart、C#、CLI。这些代码不是手写的，而是由 code-examples.ts 根据预设的options对象统一生成——每个语言都有对应的值格式化函数（如 PHP 数组、Python dict、Go 的map[string]any{}、C# 的JsonObject初始化器）。

以sunrise预设为例，各语言生成的代码形态如下：

JavaScript（传入样式实例与选项）：

new Avatar(style, { backgroundColor: ["ffd5a8", "ff9db4"], backgroundColorFill: "linear", backgroundColorAngle: 45 });

PHP：

new Avatar($style, [ 'backgroundColor' => ['ffd5a8', 'ff9db4'], 'backgroundColorFill' => 'linear', 'backgroundColorAngle' => 45 ]);

Rust：

Avatar::new(&style, json!({ "backgroundColor": ["ffd5a8", "ff9db4"], "backgroundColorFill": "linear", "backgroundColorAngle": 45 }))?;

Go（注意 gofmt 风格的行尾逗号）：

dicebear.NewAvatar(style, map[string]any{ "backgroundColor": []any{"ffd5a8", "ff9db4"}, "backgroundColorFill": "linear", "backgroundColorAngle": 45, })

Dart：

Avatar(style, { 'backgroundColor': ['ffd5a8', 'ff9db4'], 'backgroundColorFill': 'linear', 'backgroundColorAngle': 45, });

C#：

new Avatar(style, new JsonObject { ["backgroundColor"] = new JsonArray("ffd5a8", "ff9db4"), ["backgroundColorFill"] = "linear", ["backgroundColorAngle"] = 45, });

CLI（由 api.ts 的getAvatarApiCommand生成，数组选项展开为重复参数）：

dicebear create avataaars \ --backgroundColor 'ffd5a8' 'ff9db4' \ --backgroundColorFill 'linear' \ --backgroundColorAngle 45

HTTP API：文档站点会为每个预设生成对应的查询串（getAvatarApiUrl），规则是：数组选项以逗号连接为单个参数值，对象选项编码为key:value对，且idRandomization、fontFamily、fontWeight、title四个选项会被静默丢弃（HTTP API 暂不支持）。例如full-cast预设对应的查询串形态为：

?accessoriesProbability=100&facialHairProbability=100

所有语言示例都以「预设选项集」为单位整体生成，这正是预设的复用价值：你不需要逐项抄选项，复制一个页签的代码即可。另外，颜色值在预设 JSON 中以不带#的十六进制存储，文档生成的代码片段保持原样；而在编辑器 getAvatarOptions.ts 中则会在组装时统一补上#（styleOption.isColor ?#${avatarOption}: avatarOption），两种形式核心库都能接受。

概率选项与变体选项的联动

编辑器源码还揭示了概率选项与变体选项的换算规则（getAvatarOptions.ts）：

if (styleOption.hasProbability) { const componentName = key.replace(/Variant$/, ''); result[`${componentName}Probability`] = avatarOption ? 100 : 0; }

即在 UI 中选中某个变体时，对应组件的概率会被置为 100；取消则为 0。预设文件里直接写accessoriesProbability: 0/100是等价的底层表达，无需经过这一换算。

六、在 Playground 中继续调参

每个预设行都有「Playground」按钮，跳转 URL 由 SitePresetRow.vue 生成：

/playground/?style=avataaars&preset=<preset.id>

id是 kebab-case 且稳定不变（见StylePreset类型注释），所以这个 URL 可以作为书签或链接分享。打开后预设的选项已经就位，你可以在此基础上继续拖拽、切换颜色与变体，然后复制最终代码——这正是官方推荐的「预设 + 微调」工作流。

七、「还能生成多少个不同头像」是怎么算出来的

画廊每一行都标注了「N distinct avatars」，这个数字不是预设文件里手写的，而是在 SitePresetRow.vue 中实时计算的：

const count = computed(() => props.definition ? computeCount(narrowDefinition(props.definition, props.preset.options)) : undefined, );

原理是：先用预设的选项把样式定义收窄（narrowDefinition），再统计剩余的组合数（computeCount）。因此：

• 预设固定的选项（如把所有颜色组锁成单色、概率拉满）会显著减少组合数；
• 预设没有碰的选项（如 seed 本身）仍然在计数范围内自由变化；
• 计数口径与 Playground 展示的数值一致（StylePresetDialog注释特别强调「The same number the playground reports」），避免出现「预设看着多样、实际只有几套」的误导。

例如bare只固定两个概率为 0，full-cast只固定两个概率为 100，它们对组合数的削减都很小；而sepia/greyscale/duotone锁定了全部六个颜色组，多样性主要靠发型、表情与同一 ramp 内的多个色阶来维持。

八、预设质量保障：validate-presets.ts 是如何防止预设「悄悄烂掉」的

预设是冻结的选项集，最大的风险是样式定义更新后预设悄然失配：某个组件被重命名，旧预设里的<name>Variant选项不再匹配任何变体，该组件就直接不再出现，而文档构建流程根本不会察觉。为此仓库提供了专门的校验脚本 validate-presets.ts，运行方式：

node scripts/validate-presets.ts

它针对每个预设文件执行以下检查（全部可追溯到源码）：

1. 必填字段：id、name、summary、description必须是非空字符串；
2. ID 规范：id必须符合 kebab-case（/^[a-z0-9]+(-[a-z0-9]+)*$/），且全文件内不得重复；
3. 选项键合法性：每个选项键必须存在于该样式的OptionsDescriptor中，否则报错（preset "xxx" sets "key", which this style does not accept）；
4. 枚举值校验：对封闭枚举，逐一比对变体名是否仍存在于当前样式定义中；
5. 真实渲染校验：使用 6 个探测 seed（Felix、Aneka、Milo、Luna、Dara、Erik）分别渲染，任何一个 seed 渲染失败即报错——因为单 seed 可能恰好落在某个有效变体上掩盖问题；渲染结果若不含<use（即空头像），说明概率或变体选项把组件全部移除了，同样报错；
6. HTTP API 一致性警告：<key>ColorOrder选项尚未被公开 HTTP API 支持、以及会被getAvatarApiUrl静默丢弃的idRandomization/fontFamily/fontWeight/title，都会产生警告，避免画廊里展示的 HTTP API 链接与本地渲染不一致；
7. 预览 seed 存在性：校验该样式在previewRowSeeds表中有记录，否则提示重跑scripts/generate-preview-seeds.ts。

这套「渲染即验证」的思路值得借鉴：与其静态比对选项，不如直接用与库相同的校验器和解析器把每个 seed 渲染一遍，任何无法满足的颜色约束或越界值都会在这里暴露，而不是等到用户浏览器里。

九、如何读懂并复用一套预设：三步工作流

综合以上机制，把预设用进自己项目的推荐路径是：

1. 打开预设页：在 Avataaars 预设页 中，同一行三个头像使用相同 seed，直接对比不同预设在同一 seed 下的差异；每行标注的「N distinct avatars」提示你选择多样性足够高的预设；
2. 复制代码或走 Playground：点「Code」复制对应语言的完整选项对象，或点「Playground」在/playground/?style=avataaars&preset=<id>中基于预设继续微调，调完再复制；
3. 按需改写：预设只是普通选项，你可以只取其中一部分（例如只要sunrise的渐变背景参数，或只要night-shift的背景色），与自己的选项合并。预设没有「版本」概念，数据就是 avataaars.json 里的普通 JSON，想自定义时直接以其为模板修改即可。

值得留意的是，description字段按 Markdown 编写，因为文档站点的 llms.txt 镜像会把它原样输出到 Markdown 文件（见StylePresetDialog.vue中关于反引号代码片段的注释）——也就是说，预设的「设计理由」不仅是给人看的说明，也会进入机器可读的文档索引，这正是理解每套预设取舍的第一手资料。

• UI组件
• 后端