Ventoy启动主题定制：theme.txt、字体与图标排错指南

插上一个 U 盘，里面躺着十几个系统镜像，开机按快捷键，屏幕上蹦出一排白字黑底的菜单——这是大多数人做多合一启动盘时的第一印象。Ventoy 把这件事的门槛压到了最低：装一次，之后镜像文件直接往里拷，开机自然出现在菜单里，不用反复格式化。可用了两三个月，问题就浮上来了：菜单永远是那个默认模样，几十个镜像排成一条长龙，文件名密密麻麻挤在一起，眼睛要在屏幕上反复横扫才能锁定目标。于是很多人开始折腾 Ventoy 启动主题。

这件事表面看就是换个背景图，实际动手才知道门道不少：改完没反应、中文字全变成方块、在一台机器上好好的换台机器背景被拉得不成样子、图标明明放进去了菜单上就是不显示。这篇就把 Ventoy 启动主题从目录结构、配置文件、theme.txt 逐段语法，到字体转换和图标匹配规则，完整拆一遍，中间穿插我自己反复试错攒下来的判断标准。

1. 先搞清楚是谁在画这个菜单

1.1 Ventoy 只负责递菜单，渲染是它内置的那套 GRUB2 干的

很多人第一反应是"Ventoy 的主题"应该有自己一套私有格式，其实不是。Ventoy 的启动流程大致是这样：优盘被划成两部分，一个几十兆的小引导分区放引导程序，剩下的数据分区放你的镜像文件和配置。开机时主板固件加载引导程序，程序在内存里搭一个轻量运行环境，扫描数据分区里的镜像文件，为每个文件生成一条菜单项，最后把这些菜单项交给内置的 GRUB2 去渲染成你看得见的界面。

关键就在最后一步。真正把像素画到屏幕上的是 GRUB2，不是 Ventoy。所以所谓 Ventoy 启动主题，本质就是一份 GRUB2 主题。theme.txt的语法、字体必须是特定二进制格式、图标按 class 名匹配、背景图支持哪几种编码——全是 GRUB2 的规矩，跟 Ventoy 自身没半点关系。想通这一层，后面很多"为什么"就自动有答案了：为什么 TTF 字体丢进去完全没用，因为 GRUB2 的字体加载器根本不认这个格式；为什么背景图有时候颜色发灰，因为解码器对不同色彩空间的支持程度不一样；为什么图标尺寸写死了就不能自适应，因为 GRUB2 的图标绘制是固定像素贴图，不做缩放。

另外一个容易忽略的点：GRUB2 运行在一个极度精简的环境里，没有操作系统、没有显卡驱动、没有字体服务。它能用的只有固件提供的那点图形能力，加上自己内置的几个解码器。你在 Windows 里双击就能预览的效果，在这个环境里可能完全不是一回事。这也是为什么主题调试必须真机重启验证，光看文件是看不出问题的。

1.2 主题文件必须放在数据分区，别往引导分区塞

位置这件事必须先说清楚，因为放错了后面全是白费功夫。优盘插上电脑，你会看到至少一个可写的盘符，那是数据分区。主题目录放在这个分区的根目录下：

/ventoy/theme/你的主题名/

注意是数据分区的根，不是某个子文件夹里。有些人习惯把东西全塞进一个"工具"目录，主题也放进去，结果配置文件里的路径就得跟着改，一改就容易错。老老实实按/ventoy/theme/xxx/这个结构来，路径短、层级浅、不容易出岔子。

那个几十兆的小分区是引导分区，里面装的是引导程序和它的运行库。往里面写文件有两个风险：一是分区空间本来就紧张，塞几张高清背景图可能就满了，直接导致引导失败；二是某些环境下这个分区是只读挂载的，写了也白写。所以不管出于什么理由，主题相关的所有文件一律放数据分区。

1.3 一个能跑起来的主题目录，最少要有这些内容

初次上手建议先别急着做全套，就准备一份theme.txt加一张背景图，把流程跑通、确认能生效，再往里加字体和图标。一次性堆太多东西，出问题时你根本分不清是哪一环坏了。

2. ventoy.json 里那几个开关，填错就全盘失效

2.1 最小可用的主题配置块长什么样

主题要在配置文件里挂上去才会被加载。这个文件叫ventoy.json，位置同样在数据分区根目录下的ventoy文件夹里，也就是/ventoy/ventoy.json。里面关于主题的部分大概是这样：

{ "theme": { "file": "/ventoy/theme/mytheme/theme.txt", "gfxmode": "1920x1080", "display_mode": "GUI" } }

file这一项是主题描述文件的绝对路径，从数据分区根开始写，用正斜杠。这里有个小陷阱：路径里的目录名和文件名，尽量避免中文、空格和特殊符号。GRUB2 的路径处理在某些版本上对这些字符不够友好，明明文件在那儿却报找不到。统一用英文小写加连字符，是最省心的做法。

还有一点，ventoy.json是一份严格的 JSON。多一个逗号、少一个引号、写了一句//注释，整份配置就会被解析器判定为无效，然后 Ventoy 直接回退到默认外观——而且它不会给你任何提示，你只会觉得"我改了怎么没反应"。所以每次改完这个文件，先找个在线的 JSON 校验器过一遍，或者用支持语法高亮的编辑器看一眼有没有标红，能省掉大量莫名其妙的排查时间。

2.2 gfxmode 别一上来就写 1920x1080

这一项决定界面渲染的分辨率，也是新手翻车最集中的地方。写个 1920x1080，在你那台新买的显示器上确实很清晰，但拿到一台老机器上，或者在传统的兼容启动模式下，固件能提供的图形模式可能只有 1024x768 甚至 800x600。这时候会怎样？背景图被硬生生拉伸或裁剪，菜单项的位置偏移，字体边缘糊成一片。

根本原因在于两种启动模式走的图形接口不同。新式的统一可扩展固件接口走的是图形输出协议，普遍支持到 1920x1080 甚至更高；传统兼容模式走的是更老的视频扩展标准，可选模式非常有限，1080p 基本别想。而同一支优盘，你在不同机器上可能分别以这两种模式启动，所以主题必须考虑兼容性。

我的做法是填"max"，让 GRUB2 自己跟固件协商一个可用的最大模式。这样在新机器上拿到高分屏，在老机器上自动降级，不至于花屏。代价是"最大"未必等于你背景图的原生分辨率，背景还是可能被缩放，所以背景设计本身要留好余量——主体元素集中在画面中央三分之一到一半的区域，边缘用纯色或渐变延伸出去，这样无论怎么裁切都不会切掉关键内容。

想精确知道某台机器支持哪些模式，可以在 GRUB2 的命令行界面里执行查询命令，它会列出当前固件报告的所有可用图形模式。把这台机器的常用模式记下来，写进配置，比盲目猜要靠谱得多。

2.3 右下角那行版本小字，是可以挪位置的

界面上除了菜单，还有一行不起眼的小字，显示的是版本信息，默认贴在右下角。如果你的背景图右下角刚好有图案或文字，这行小字就会压在上面，很影响观感。配置里给了三个参数专门管它：

{ "theme": { "file": "/ventoy/theme/mytheme/theme.txt", "gfxmode": "max", "display_mode": "GUI", "ventoy_left": "5%", "ventoy_top": "92%", "ventoy_color": "#5b6b85" } }

前两个是百分比定位，从左上角算起，5%和92%大致就是左下角偏上的位置。第三个是文字颜色，写十六进制色值。这行字建议别设成跟背景完全一样——留一点点对比度，出问题时能快速确认自己加载的确实是改过的那份配置，而不是缓存的旧版本。这个小细节在排查阶段非常好用。

3. theme.txt 逐段拆开看

3.1 全局段：桌面图、底色、标题文字

文件开头这几行定义整个界面的底板：

desktop-image: "background.png" desktop-color: "#0b1220" title-text: "" title-color: "#ffffff"

desktop-image是背景图文件名，相对路径，相对的就是theme.txt自己所在的目录。这里不需要写/ventoy/theme/xxx/background.png这种绝对路径，写文件名就够了，多写反而容易出错。

desktop-color是背景图之外区域的填充色。它的价值在于兜底：当图片分辨率小于渲染分辨率，或者图片加载失败时，露出来的部分是这块颜色，而不是刺眼的纯黑或者花屏。选一个跟背景图主色调接近的深色，能让整个界面在异常情况下依然体面。

title-text是顶部标题。如果你更喜欢干净利落的界面，把它留空就行。反过来，如果你想让标题显示在自定义位置，可以先留空，再用后面提到的标签块自己画一个，位置和字体都能完全控制。

3.2 boot_menu 段：这几个数字决定菜单是舒服还是难看

菜单列表的排版全在+ boot_menu { }这个块里：

+ boot_menu { left = 12% top = 18% width = 76% height = 70% item_height = 44 item_padding = 8 item_spacing = 6 icon_width = 36 icon_height = 36 item_font = "MyFont 18" item_color = "#c9d3e3" selected_item_color = "#ffffff" }

left、top、width、height四个值框定了菜单的可视区域。用百分比的好处是自适应不同分辨率，代价是在极端比例下可能跟背景图对不齐。如果背景图是精心设计的、菜单必须精确落在某个框里，那就改用绝对像素，同时把gfxmode固定死，用兼容性换精确度。这两条路只能选一条，不能既要自适应又要像素级对齐。

item_height是每一行的高度，这个值跟字体大小强相关，也是最容易出问题的地方。设置得比字体实际高度小，中文字的下半部分、带下伸笔画的字符就会被切掉一截，看起来像是字被削平了。经验上，行高至少要是字号的 1.5 倍，中文界面建议给到 1.6 到 1.8 倍。比如字号 18，行高给到 30 到 34 比较稳妥，再加item_padding的上下留白，视觉上才不局促。

item_spacing是行与行之间的额外间隙，跟item_height是叠加关系。两者都调大，一屏能显示的条目就少，镜像多了就要滚动；两者都调小，又容易挤得看不清。我一般按"一屏至少显示 10 到 12 条"来倒推，这个数量对绝大多数人够用了。

3.3 选中态：颜色方案够用就别折腾九宫格切图

selected_item_color是当前高亮项的文字颜色。只改颜色最省事，改完重启就能看到效果，不需要任何图片资源。如果想要那种带半透明圆角高亮条的效果，就得用selected_item_pixmap_style配一套九宫格切图。

九宫格切图的意思是：把一张高亮条图片切成九块，四个角保持原样不拉伸，四条边单向拉伸，中间双向拉伸，这样无论菜单项多宽多高，边框都不会变形。听着高级，实操起来很磨人：切图的命名规则、每块图的尺寸、边框宽度必须严格对应theme.txt里的参数，差一个像素效果就崩。而且这套东西在高分屏和低分屏下的观感差异明显，你得为不同分辨率准备不同尺寸的素材。

我的建议是先用纯色高亮跑起来，等整个主题的布局、字体、配色都稳定了，再考虑要不要升级到切图方案。把两件事捆在一起做，出问题的时候你会分不清是布局错了还是切图错了。

4. 字体这一关：中文变方块的全套解法

4.1 GRUB2 只认它自己的字体格式

把一款中文字体直接改个扩展名丢进主题目录，是最常见的无效操作。GRUB2 的字体加载器只认一种精简过的位图字体格式，文件扩展名是.pf2。系统里那些 TTF、OTF，必须先经过转换才能用。这不是 Ventoy 的限制，是 GRUB2 的设计——它要在没有字体渲染引擎的环境里画字，只能用预先把字形烘焙好的位图字体。

这也解释了一个很多人困惑的现象：为什么明明设了字体文件，菜单上的字还是那个默认样子？因为字体没被成功加载，GRUB2 就静默回退到内置字体。内置字体通常只覆盖基本拉丁字符，中文自然全变成空心方块或者干脆什么都不显示。整个过程没有任何报错，你只能从结果反推。

4.2 转换命令的实际操作与参数取舍

转换工具叫grub-mkfont，Linux 下一般随 GRUB 的通用包一起装好了，Windows 下用子系统环境或者任意一个带这套工具的镜像环境都行。基本命令长这样：

grub-mkfont -s 18 -n "MyFont" -o MyFont18.pf2 SourceHanSans.ttf

-s是字号，这个值得跟theme.txt里引用的字号对上。-n是给这套字体起的名字，后面在theme.txt里就用这个名字引用它，不起名字的话默认用文件名，容易搞混。-o是输出路径。

中文场景下真正的麻烦是体积。一款完整的中文字体动辄几万个字形，全量转换出来的文件可能有几兆甚至十几兆，而这个文件会被加载到内存里。加载时间变长，开机到菜单出现的那几秒钟里你会明显感觉到卡顿。如果只是自己用、镜像数量不多，这点延迟可以接受；如果是在多台机器上反复插拔，就有点难受了。

压缩体积的办法是只转换实际用得到的字符范围。转换工具支持指定码点区间，只把常用汉字区烘焙进去，文件能小一大截。代价是遇到生僻字就显示不出来——如果你的镜像文件名里有可能出现生僻字，那就老老实实全量转，别为了省那点体积给自己埋雷。这里有个折中思路：文件名本身用常见的汉字，生僻字用拼音或英文代替，这样字体只需要覆盖常用区，两全其美。

4.3 字号、行高、基线的三角关系

字体转换好了、theme.txt里也引用了，结果发现字的下半截被切掉——问题往往不在字体，而在行高。

字体的度量里有几个概念：上伸高度是字符从基线往上能到多高，下伸高度是从基线往下能到多低。中文字符一般比较方正，但带竖弯钩、带下伸笔画的字仍然会突破常规高度。行高如果只按字号给，等于把上下都卡死了，那些稍微越界的笔画就被裁掉。

稳妥的做法是行高给到字号的 1.6 倍以上，同时留出item_padding。另外转换时可以手动指定上伸和下伸的度量值，让字体自身报告的尺寸跟你的行高匹配，这样排版会更精准。不过这条属于微调范畴，先把行高放大到不切字，再考虑要不要精修。

还有一个现象值得提一句：同一个字号，在两种启动模式下的观感可能不一样。因为底层图形接口不同，字体的光栅化结果会有细微差异，一个模式下清晰，另一个模式下可能发虚。如果特别在意，可以准备两套配置，按启动模式分别指定不同的字号，不过对绝大多数使用场景来说，这点差异不值得大动干戈。

5. 图标不显示，多半是名字没对上

5.1 菜单项的 class 决定了它配哪个图标

GRUB2 的图标机制很简单：每条菜单项身上挂着若干 class 标签，绘制时按顺序去icons/目录里找跟 class 同名的 PNG 文件，找到哪个用哪个，全都没找到就不显示图标。所以"图标不显示"这件事，九成九是文件名跟 class 名对不上。

Ventoy 在扫描镜像时会根据文件类型和里面的内容给菜单项打标签，标签统一带一个固定的前缀。常见的有对应光盘镜像的、对应映像文件的、对应可执行引导文件的、对应虚拟磁盘的等等。它还会尝试进一步识别镜像里装的是什么系统，给出更细的分类标签。

问题在于，不同版本的标签集合可能不完全一致，网上抄来的配置未必跟你手上的版本对得上。最靠谱的参照物是什么？找一份官方发布的主题示例包，打开它的icons目录，里面那些文件名就是当前版本会用到的全部 class 名。照单抓药，把每个名字都配上对应图标，一个不漏，基本就不会出错。这比在网上到处搜"图标要叫什么名字"高效得多。

5.2 图标尺寸和格式的硬性约束

几个必须守住的点：格式必须是 PNG，需要透明背景就带 alpha 通道，不要用别的格式改扩展名糊弄。尺寸上建议用 2 的幂，32 或 64 是最常见的档位，跟boot_menu里的icon_width、icon_height保持一致。图标做多大就写多大，不要指望它自动缩放——GRUB2 是直接按像素贴上去的，尺寸不匹配就是拉伸变形或者显示不全。

图标风格统一这件事被很多人低估。从不同地方东拼西凑来的图标，有的圆角有的直角，有的扁平有的立体，有的白底有的透明，摆在一列里格外杂乱。要么统一用同一套素材，要么自己按同一套规范重画一遍：同样的画布尺寸、同样的视觉重心、同样的配色区间。我试过混搭，最后还是老老实实重做了一套，观感差别非常明显。

5.3 特殊镜像想单独换个图标怎么办

默认的 class 是按文件类型和内容识别出来的，有些自制的、非标准结构的镜像可能识别不出具体类型，只能落到最通用的那个分类上，所有这类镜像长得一模一样。想让某几个特别常用的镜像在列表里一眼就能认出来，可以走菜单别名这条路——在配置里给指定路径的镜像起一个专属名字。别名改的是显示文字，配合着把镜像文件名本身也改成有意义的短名，实际效果比换图标强得多。

说句实话，图标的信息密度其实不高，与其花两小时给每个镜像配图标，不如花十分钟把文件名改清楚。一行"系统维护工具集"比一个模糊的小图标有用得多。

6. 主题不生效时的排查链路

6.1 第一层：配置文件到底有没有被读到

改完重启发现毫无变化，先别怀疑主题文件本身，从最外层往里查。第一步，确认ventoy.json的语法完全合法。随便找个校验工具过一遍，或者把它临时改名，看看界面有没有变化——如果改名前后完全一样，说明系统压根没读到这份配置，问题在路径或者分区上。

第二步，确认文件位置。ventoy.json必须在/ventoy/目录下，主题目录必须在/ventoy/theme/下。有些人把ventoy目录建成了Ventoy，在 Windows 的资源管理器里看不出区别，但某些环境下大小写是敏感的。统一小写能规避一整类问题。

第三步，确认路径分隔符。配置里一律用正斜杠，别用反斜杠。反斜杠在某些解析器里是转义字符，写进去可能被吃掉，导致路径拼错。

第四步，看看有没有多余的文件干扰。有些人习惯性地把备份文件也留在同一个目录里，比如ventoy.json.bak。虽然一般不会影响，但目录越干净，排查越省心。

6.2 第二层：主题加载了但显示不对

如果确认配置生效了（比如右下角那行小字的颜色确实变了），但界面还是不对，那就是主题层面的问题。这时候分两条线查：背景不显示，查图片格式和文件名，确认desktop-image里写的名字跟实际文件名一字不差，包括扩展名；背景显示了但变形，查分辨率和gfxmode，大概率是固件协商出来的模式跟图片比例不一致。

菜单位置错乱、菜单项挤在一起或者溢出屏幕，查boot_menu里的四个坐标值和行高。这里有个容易忽略的联动：行高变大之后，同样的可视高度能放的条目变少，如果height没跟着调，菜单就会滚动，第一次用的人会以为条目少了。

文字显示成方块，查字体。文字显示了但字体明显不是自己设的，也是字体问题——大概率是字体名写错了，或者.pf2文件没放在theme.txt同级目录，加载器找不到就静默回退。

6.3 第三层：换台机器就出问题

这一层最难查，因为你的配置在常驻机器上完全正常。问题通常出在两个地方：分辨率和启动模式。老机器只有低分辨率模式，你的 1080p 背景被压缩，如果背景上的关键元素靠近边缘，就会进入菜单区域造成视觉干扰。另一个是兼容模式下的图形能力有限，透明通道的处理可能不理想，带半透明的图标或高亮条会出现难看的边缘。

应对思路是把主题做得"抗造"：背景主体居中且留足边距，不要用满屏铺满的细节纹理；图标和文字全部用高对比度的纯色，别依赖微妙的半透明过渡；布局尽量居中对称，这样在任何比例下看着都不别扭。这套原则做出来的主题可能不够惊艳，但胜在到处都能用。

7. 折腾完之后，我的几点实际体会

主题这东西，第一版永远会做过头。我最早那套加了渐变背景、发光文字、整套图标、高亮切图，看着确实好看，用起来问题一堆：老机器上背景糊成一片、切图在低分屏上边框错位、图标风格不统一反而更乱。后来全砍掉，退回纯色背景加两档文字颜色加一套最简图标，反而稳定得一批，用到现在没再动过。

背景图的设计有个反直觉的点：越简单越耐看。因为菜单会盖住画面中间一大块，你的背景在中间区域无论画了什么都会被遮住，真正起作用的只有边缘那一圈。所以背景的价值在于营造氛围，而不在于展示内容。与其绞尽脑汁画一张精美的图，不如选一个舒服的深色底加一点方向的渐变，省事又不出错。

最后一件事，别在折腾主题的过程中把优盘搞挂了。每次改配置之前，把整个ventoy目录复制一份到电脑硬盘上。真出了引导失败的情况，把备份拷回去就能恢复，不用重装。这个习惯帮我省过至少三次重装的功夫。