Starship Nerd Font Symbols 预设实战：将提示符模块图标全面切换到 Nerd Font 符号

Starship 内置了大量 shell 提示符“预设（preset）”，其中 nerd-font-symbols 预设负责把各模块默认使用的符号统一替换为 Nerd Font 专属字形。本指南以仓库中 docs/presets/nerd-font.md（及其西班牙语本地化版本 docs/es-ES/presets/nerd-font.md）为骨架，完整解析该预设的 TOML 内容、starship preset 命令行用法，并结合 src/main.rs 与 src/print.rs 的源码实现说明其背后的工作机制，帮助你一键应用并进一步定制属于自己的符号集。

Starship Nerd Font Symbols 预设渲染效果截图

预设是什么，nerd-font-symbols 做了什么

“预设”是 Starship 社区整理并随二进制一起分发的一组现成配置片段。nerd-font-symbols 预设的目标非常聚焦：逐个模块修改 Starship 的 symbol（以及部分 full_symbol、ssh_symbol、read_only 等）配置项，让提示符中出现的图标统一采用 Nerd Font 字形。

未安装 Nerd Font 的终端只能渲染 emoji 或普通 Unicode 字符；而安装并启用 Nerd Font 后，终端便有能力渲染数千个带语义的图标字形（如 Git 分支、编程语言徽标、操作系统 Logo、电池电量等）。该预设正是把这些图标全面接入提示符的最直接方式。

对应的完整配置文件位于 docs/public/presets/toml/nerd-font-symbols.toml，同一文件同时被文档与二进制构建引用（下文“源码实现验证”一节会给出证据）。

前置条件

应用本预设之前，你需要满足：

• 终端里已安装并启用一款 Nerd Font（官方示例使用 Fira Code Nerd Font）。Nerd Font 是对常见编程字体（Fira Code、JetBrains Mono、Hack 等）的补全版本，额外合入了 Font Awesome、Devicons、Material Design Icons、Powerline Symbols 等字形集合。
• 安装好 Starship 本体，并且能够在你的 shell 中正常加载（各 shell 的初始化脚本可参考 docs/installing/README.md）。

提示：如果运行后提示符里的图标显示为方框、豆腐块或空白，通常是终端没有启用 Nerd Font，或启用的字体不完整——请检查终端设置中的字体配置。

快速应用：starship preset 命令详解

Nerd Font Symbols 预设的使用方式只有一条命令（原文档的“Configuration”一节）：

starship preset nerd-font-symbols -o ~/.config/starship.toml

命令作用是把内置的 nerd-font-symbols 预设内容写入 ~/.config/starship.toml。为了让这条命令更可控，可以了解 starship preset 的完整参数——其 CLI 定义位于 src/main.rs：

参数	作用	说明
<name>（位置参数）	要输出的预设名称	属于枚举值，必须是编译期内置的预设名之一；传错名称会直接报错，见 src/print.rs 中 ValueEnum for Preset 的实现（src/print.rs）
-o, --output <path>	把预设写到文件而不是标准输出	与 --list 互斥；底层使用原子的文件写入
-f, --force	目标文件已存在时强制覆盖	必须与 -o/--output 搭配使用
-l, --list	列出全部可用预设名称	不写文件，仅打印列表

几种常见用法示例：

# 1. 在终端直接预览预设内容（输出到标准输出）
starship preset nerd-font-symbols

# 2. 覆盖写入全局配置文件（文件已存在时需要 -f）
starship preset nerd-font-symbols -o ~/.config/starship.toml -f

# 3. 查看当前可用预设清单
starship preset --list

上述命令的处理逻辑实现在 src/print.rs 的 preset_command() 中：先通过 shadow::get_preset_content(name) 取回编译期嵌入的 TOML 内容，若提供了 --output 则经 write_file_atomic 写盘（失败时打印错误并退出），否则直接打印到标准输出。值得注意的是，仓库还包含针对 preset_command 的单元测试（src/print.rs），其中 preset_command_output_to_file 断言了 nerd-font-symbols 预设写出内容与源文件 include_str!("../docs/public/presets/toml/nerd-font-symbols.toml") 完全一致，这证实了文档中展示的 TOML 正是二进制实际内置的内容。

应用前后必读：备份与还原

• 覆盖 ~/.config/starship.toml 前，建议先备份现有配置：

  cp ~/.config/starship.toml ~/.config/starship.toml.bak
  

• 若想回到“纯默认外观”，删除或移走配置文件即可（Starship 在无配置时使用内置默认值），也可把备份恢复回去。

• 预设写入的是静态配置快照，不会自动跟随 Starship 版本更新；升级后如需同步最新预设内容，可重新执行上述命令。

预设内容全解析：逐个模块的符号替换

nerd-font-symbols 预设的配置里，绝大部分 [模块] 段只改一个 symbol 字段，少数模块会修改更专用的字段。其顶层还声明了 JSON Schema：

"$schema" = 'https://starship.rs/config-schema.json'

schema 字段让支持 JSON Schema 的编辑器（如 VS Code 配合 TOML 插件）在编辑配置文件时获得自动补全与校验提示，对应的 Schema 文件就在仓库的 docs/public/config-schema.json。

下面按类别拆解符号改动，方便快速检索每个模块。

云服务与远程平台

aws、azure、gcloud、openstack 模块分别使用 、、``、󰡖 图标；container 与 singularity（容器/沙箱环境）使用容器图标。这一组的原始定义对应 src/configs/aws.rs、src/configs/azure.rs、src/configs/gcloud.rs、src/configs/openstack.rs 等模块的 symbol 默认值，预设只是在配置层覆盖它们。

编程语言与运行时

这是预设中覆盖范围最大的一组，包括：

• C 系：c（）、cpp（）、cobol（、fortran（）、zig（`）
• 脚本/动态语言：python（、ruby（）、perl（）、lua（）、php（）、raku（）、red（`）
• JVM/.NET 生态：java（）、scala（）、kotlin（）、dotnet（）、gradle（）、maven（）
• 新兴/小众语言：mojo、odin、purescript、gleam、typst、solidity、daml、raku、red、haxe 等
• 数据与科学计算：rlang（）、julia（）、quarto 未单独出现，但 pixi、conda 使用对应环境图标

对应源码模块位于 src/modules 下的同名文件中（如 python.rs、rust.rs），预设只影响其渲染的符号，不改变模块的探测逻辑与显示内容。

包管理器与构建工具

cmake、meson、xmake、gradle、maven、package、pixi、spack、helm 等模块被替换为对应工具图标；buf 使用 、bun使用、deno 使用 `，三者分别是 Protobuf 工具链与两类 JS 运行时。

版本控制与代码协作

git_branch（）、git_commit（其 tag_symbol被改为 ﯐，注意开头带空格）、hg_branch、jj_bookmark、fossil_branch、pijul_channel` 统一使用 Git 分支样式图标。这些模块对应 src/configs/git_branch.rs、src/configs/git_commit.rs、src/configs/hg_branch.rs 等。

系统状态与环境信息

• battery：full_symbol（󰁹）、charging_symbol（󰂄）、discharging_symbol（󰂃）、unknown_symbol（󰂑）、empty_symbol（󰂎）五种电量状态各配一个专属字形（默认只用 charging_symbol 和 discharging_symbol）。
• directory：把 read_only 图标改为 󰌾（前导空格 + 只读锁形图标），只读目录会追加该标识。
• hostname：将 ssh_symbol 改为 SSH 图标 󰁁，仅在通过 SSH 连接时显示主机名时使用。
• memory_usage（󰍛）、shlvl（󰹍）、status（，命令退出码非零时显示）、sudo（）等状态类模块同步替换。

操作系统图标表 [os.symbols]

预设中还定义了庞大的 [os.symbols] 子表（对应 os 模块配置），把各类操作系统/发行版名称映射到专属 Logo，例如：

[os.symbols]
Alpine = "󰌀"
Arch = "󰌃"
Debian = "󰌆"
Fedora = "󰌊"
Macos = "󰌂"
NixOS = "󰌓"
Ubuntu = "󰌛"
Windows = "󰍲"
# …更多发行版（AlmaLinux、CentOS、Gentoo、Manjaro、openSUSE、Pop、RockyLinux、Void、Zorin 等）见完整文件

os 模块会根据当前系统检测出的发行版名称在表中取对应字形。由于符号值普遍自带一个尾部空格，图标与模块文字之间会自动留白，无需额外配置分隔符。

完整 TOML 原文

为便于复制与离线查阅，此处给出 docs/public/presets/toml/nerd-font-symbols.toml 的完整内容（这也是二进制内嵌并实际生效的配置）：

"$schema" = 'https://starship.rs/config-schema.json'

[aws]
symbol = " "

[azure]
symbol = " "

[battery]
full_symbol = "󰁹 "
charging_symbol = "󰂄 "
discharging_symbol = "󰂃 "
unknown_symbol = "󰂑 "
empty_symbol = "󰂎 "

[buf]
symbol = " "

[bun]
symbol = " "

[c]
symbol = " "

[cpp]
symbol = " "

[cmake]
symbol = " "

[cobol]
symbol = " "

[conda]
symbol = " "

[container]
symbol = " "

[crystal]
symbol = " "

[dart]
symbol = " "

[deno]
symbol = " "

[direnv]
symbol = " "

[directory]
read_only = " 󰌾"

[docker_context]
symbol = " "

[dotnet]
symbol = " "

[elixir]
symbol = " "

[elm]
symbol = " "

[erlang]
symbol = " "

[fennel]
symbol = " "

[fortran]
symbol = " "

[fossil_branch]
symbol = " "

[gcloud]
symbol = " "

[gleam]
symbol = " "

[git_branch]
symbol = " "

[git_commit]
tag_symbol = '  '
[golang]
symbol = " "

[gradle]
symbol = " "

[guix_shell]
symbol = " "

[haskell]
symbol = " "

[haxe]
symbol = " "

[helm]
symbol = " "

[hg_branch]
symbol = " "

[hostname]
ssh_symbol = " "

[java]
symbol = " "

[jj_bookmark]
symbol = " "

[julia]
symbol = " "

[kotlin]
symbol = " "

[kubernetes]
symbol = " "

[lua]
symbol = " "

[maven]
symbol = " "

[memory_usage]
symbol = "󰍛 "

[meson]
symbol = " "

[mojo]
symbol = " "

[nats]
symbol = " "

[netns]
symbol = " "

[nim]
symbol = " "

[nix_shell]
symbol = " "

[nodejs]
symbol = " "

[ocaml]
symbol = " "

[odin]
symbol = " "

[opa]
symbol = " "

[openstack]
symbol = " "

[os.symbols]
AIX = " "
AlmaLinux = " "
Alpaquita = " "
Alpine = " "
ALTLinux = " "
Amazon = " "
Android = " "
AOSC = " "
Arch = " "
Artix = " "
Bazzite = " "
Bluefin = " "
CachyOS = " "
CentOS = " "
Debian = " "
DragonFly = " "
Elementary = " "
Emscripten = " "
EndeavourOS = " "
Fedora = " "
FreeBSD = " "
Garuda = " "
Gentoo = " "
HardenedBSD = " "
Hurd = " "
Illumos = " "
InstantOS = " "
Ios = " "
Kali = " "
KDENeon = " "
Linux = " "
Mabox = " "
Macos = " "
Manjaro = " "
Mariner = " "
MidnightBSD = " "
Mint = " "
NetBSD = " "
NixOS = " "
Nobara = " "
OpenBSD = " "
OpenCloudOS = " "
openEuler = " "
openSUSE = " "
OracleLinux = " "
PikaOS = " "
Pop = " "
Raspbian = " "
Redhat = " "
RedHatEnterprise = " "
Redox = " "
RockyLinux = " "
Solus = " "
SUSE = " "
Ubuntu = " "
Ultramarine = " "
Unknown = " "
Uos = " "
Void = " "
Windows = " "
Zorin = " "

[package]
symbol = "󰏗 "

[perl]
symbol = " "

[php]
symbol = " "

[pijul_channel]
symbol = " "

[pixi]
symbol = "󰏗 "

[pulumi]
symbol = " "

[purescript]
symbol = " "

[python]
symbol = " "

[raku]
symbol = " "

[red]
symbol = " "

[rlang]
symbol = " "

[ruby]
symbol = " "

[rust]
symbol = "󱘗 "

[scala]
symbol = " "

[shlvl]
symbol = "󰹍 "

[singularity]
symbol = " "

[solidity]
symbol = " "

[spack]
symbol = " "

[status]
symbol = " "

[sudo]
symbol = " "

[swift]
symbol = " "

[terraform]
symbol = " "

[vlang]
symbol = " "

[typst]
symbol = " "

[vagrant]
symbol = " "

[xmake]
symbol = " "

[zig]
symbol = " "

说明：Git 与不少 Markdown 渲染器在展示时可能剥落行尾空格，因此上方代码块里各 symbol 值末尾的空格在网页上不一定可见。实际生效配置中这些字形几乎都带一个尾随空格（如 git_branch 的 symbol = " "），以保证图标与文字之间的间距。若要精确获取带空格的原文，请直接执行 starship preset nerd-font-symbols 输出，或阅读仓库里的 nerd-font-symbols.toml。

符号字段在源码中如何被消费

Starship 每个模块的配置结构都由 src/configs/*.rs 中对应的 *Config 结构体描述，其中 symbol 几乎都是基础字段。以 Git 分支为例，src/configs/git_branch.rs 会声明 symbol 及 truncation_length、format 等字段的默认值，模块渲染逻辑（src/modules/git_branch.rs）在组装 segment 时把该符号拼入 format 的 $symbol 占位符。因此用户配置中的 symbol = "…" 会直接覆盖内置默认值——这也是预设能“一键换肤”而不触碰任何代码的原因。

从源码结构还可以推断：所有预设 TOML 是在构建期通过 shadow（构建信息模块）嵌入可执行文件的，preset_command 只是把它们当作普通静态内容输出（参见 src/print.rs 与单元测试 src/print.rs）。这意味着离线环境也能使用 starship preset，无需联网下载。

进阶：在此预设基础上做个性化微调

把预设写入配置文件后，它就是一份普通 TOML，可以任意叠加自己的修改：

# ~/.config/starship.toml（在 preset 内容之后追加）
[git_branch]
symbol = ""

[status]
symbol = ""

# 若不需要某个模块图标，直接隐藏模块亦可
[package]
disabled = true

需要注意两点：

1. 后写覆盖先写：TOML 中同一键重复出现时，以最后出现者为准；把自定义段放在文件末尾更直观，或者干脆删去预设里不想保留的段落。
2. 模块探测行为不受影响：预设只改符号显示，不会改变 Starship 判断“当前处于 Git 仓库”“已激活某语言环境”等逻辑，所以不会因换图标造成误判。

与其他符号类预设的取舍

• No Nerd Fonts 预设（对应 TOML 见 docs/public/presets/toml/no-nerd-font.toml）：反向思路——把符号限制在 emoji 与 Powerline 集合内，即使没有安装 Nerd Font 也能正常渲染所有图标；该预设未来版本的 Starship 中有望成为默认预设（见 docs/presets/README.md）。若团队协作环境无法统一安装 Nerd Font，建议选它而非 nerd-font-symbols。
• Plain Text Symbols 预设：把符号替换为纯文本缩写，适合完全无法使用 Unicode 的场景。
• 其余社区预设（如 bracketed-segments、tokyo-night、gruvbox-rainbow 等）侧重配色与版式，可与 nerd-font-symbols 的风格灵感互为参考；完整列表见 docs/presets/README.md。

常见问题排查

• 图标显示为方框/空白：几乎总是字体问题。确认终端设置的字体是完整 Nerd Font，并且重启终端或重新加载 shell 配置。
• 执行 starship preset 报“未知预设”：先运行 starship preset --list 确认内置预设名拼写（nerd-font-symbols 中的连字符不要遗漏）。
• 写入文件失败：目标配置目录不存在、或无写权限时命令会报错退出；确保 ~/.config 目录存在，或改用 -o 指定其它路径。
• 改完想整体回退：删除配置文件并让 Starship 以内置默认渲染，或从备份恢复 ~/.config/starship.toml.bak。

小结

nerd-font-symbols 预设通过覆盖几十个模块的符号字段，把 Starship 提示符的图标体系整体切换到 Nerd Font 字形。它的实现完全依赖“预设 = 静态 TOML 配置、构建期内嵌、命令期输出”这套机制，你可放心用 starship preset nerd-font-symbols -o ~/.config/starship.toml 一键套用，再基于 完整 TOML 按需增删，最终做出既美观又契合自己工具链的专属提示符。