Starship No Nerd Font Preset 详解：让提示符符号在不安装 Nerd Fonts 时也能正常显示

Starship 的预设（Preset）机制允许用户用一条命令切换整套配色与符号方案。本文围绕官方预设文档中的 No Nerd Fonts Preset 展开，完整保留该预设的官方配置内容与应用命令，并结合 Starship 源码逐节解析 starship preset 子命令的构建期嵌入机制、参数行为，以及预设中五个模块符号（Azure、Battery、Erlang、Node.js、Pulumi）在各模块源码里的实际生效位置，帮助读者既会用它、也明白它为什么有效。

预设定位：只使用 Emoji 与 Powerline 符号集

No Nerd Fonts Preset 的目标很明确：把提示符中所有模块的符号限制在 Emoji 和 Powerline 两个符号集之内。由于 Nerd Font（Nerd Fonts 项目扩展后的字体）并非所有终端的默认字体，若模块使用了 Nerd Font 专有符号（如 󰉍、󰄈 这类私有区码位字符），在未安装 Nerd Font 的终端上就会显示为空白或方框。

该预设的作用等价于"零依赖安装"：即使系统没有安装任何 Nerd Font，所有模块符号也能正常渲染。官方预设索引（docs/presets/README.md）还特别以 TIP 提示框标注：该预设将在 Starship 的某个未来版本中成为默认预设（对应上游 PR 3544），也就是说当前默认符号集正在向"无 Nerd Font 也能看"的方向收敛，现在启用它属于提前对齐未来默认行为。

与相关预设的区分：

预设	符号策略	适用场景
No Nerd Fonts（本文）	仅 Emoji + Powerline 符号	未装 Nerd Font、希望开箱即看全符号
Nerd Font Symbols	全量替换为 Nerd Font 符号	已安装 Nerd Font、追求统一图标风格
Plain Text Symbols	纯 ASCII 文本	终端完全不支持 Unicode

Nerd Font 预设的完整配置可参考 docs/public/presets/toml/nerd-font-symbols.toml，与本预设形成对照。

一条命令应用预设

官方文档给出的应用方式（本预设对应文档为 docs/ar-SA/presets/no-nerd-font.md，与英文版 docs/presets/no-nerd-font.md 内容一致）：

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

执行后，~/.config/starship.toml 会被写入该预设的全部配置。-o（--output）参数指定把预设内容写入文件而非打印到标准输出。

从源码看，preset 子命令的完整参数定义在 src/main.rs：

• name：预设名，value_enum 校验，取值列表不是硬编码的（后文说明）；required_unless_present("list") 表示不传 --list 时必填；
• output（-o/--output）：输出到指定文件，与 list 互斥（conflicts_with = "list"）；
• force（-f/--force）：目标文件已存在时强制覆盖，依赖 output 参数（requires = "output"）；不加该参数时，若 ~/.config/starship.toml 已存在，写入会失败并提示，避免误覆盖你手写的配置；
• list（-l/--list）：仅列出所有可用预设名，不输出内容。

命令的实际执行逻辑在 src/print.rs 的 preset_command 中：先通过 shadow::get_preset_content(name) 取出预设文本，带 -o 时调用 crate::utils::write_file_atomic（原子写入，位于 src/utils/mod.rs）写文件，失败时以非零状态退出；不带 -o 时直接把内容写到 stdout，便于管道处理，例如 starship preset no-nerd-font | head -n 20。

预设完整配置与逐项解析

该预设的完整配置文件为 docs/public/presets/toml/no-nerd-font.toml，全文如下（这也是执行上面的 starship preset no-nerd-font -o ... 命令后落盘的内容）：

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

[azure]
symbol = "☁️ "

[battery]
full_symbol = "• "
charging_symbol = "⇡ "
discharging_symbol = "⇣ "
unknown_symbol = "❓ "
empty_symbol = "❗ "

[erlang]
symbol = "ⓔ "

[nodejs]
symbol = "⬢ "

[pulumi]
symbol = "🧊 "

预设配置遵循 Starship 通用配置文件格式（$schema 指向配置 Schema，仓库中对应 docs/public/config-schema.json；其余模块的完整参数可查阅 docs/config/README.md）。下面逐节说明每个覆盖项的含义及其在模块源码中的消费位置：

[azure]：symbol = "☁️ "

Azure 模块的 format 模板形如 on $symbol($username) / on $symbol($subscription:$username)（见 src/modules/azure.rs 中各配置分支的默认 format），模块通过把 symbol 配置值注入模板变量 $symbol 来渲染符号。默认值取自 Nerd Font 符号集，本预设将其替换为 Emoji 云 ☁️，从而在未安装 Nerd Font 时不再出现占位方框。

[battery]：五个状态符号全部 Emoji 化

Battery 模块的符号不是单个 symbol，而是按电池状态选择的五个变量。从 src/modules/battery.rs 可以看到映射逻辑：

"symbol" => match state {
    battery::State::Full => Some(config.full_symbol),
    // Charging → charging_symbol（允许被 full_symbol 回退覆盖）
    // Discharging → discharging_symbol（允许被 empty_symbol 回退覆盖）
    battery::State::Unknown => Some(config.unknown_symbol),
    battery::State::Empty => Some(config.empty_symbol),
    ...

本预设对这五个状态分别给定：

配置项	符号	含义
full_symbol	•	电池满电
charging_symbol	⇡	充电中（向上箭头）
discharging_symbol	⇣	放电中（向下箭头）
unknown_symbol	❓	电量未知
empty_symbol	❗	电量耗尽

注意源码中充电/放电符号带有 or(...) 回退链（charging_symbol.or(Some(config.charging_symbol)) 等写法出现在状态映射中），意味着同一状态下的符号存在回退取值顺序，预设只需提供常规路径上的值即可生效。

[erlang]：symbol = "ⓔ"

Erlang 模块把 config.symbol 直接作为模板变量输出（src/modules/erlang.rs 中 "symbol" => Some(config.symbol)）。默认 Nerd Font 符号被替换为带圈字母 ⓔ（Unicode 拉丁字母区块，属于常规字体覆盖范围），保持"语言标识"语义。

[nodejs]：symbol = "⬢ "

Node.js 模块同样是把 config.symbol 注入 via $symbol($version ) 模板（src/modules/nodejs.rs）。这里有一点值得注意：预设值本身就是一个 Starship 格式字符串——⬢ 中 ⬢ 是黑六边形（Unicode 几何图形区块），括号部分是 Starship 的样式语法，渲染时 ⬢ 会以加粗绿色显示。这说明模块级 symbol 配置值支持完整的 Starship 格式字符串（着色、加粗、下划线等），而不只是纯文本。

[pulumi]：symbol = "🧊"

Pulumi 模块把 config.symbol 用于 via $symbol($username@)$stack 等模板（src/modules/pulumi.rs）。默认符号替换为 Emoji 冰块 🧊（呼应 Pulumi 的"堆栈/积木"意象），Emoji 由系统 Emoji 字体渲染，不依赖 Nerd Font。

原理：预设内容是如何被打进二进制的

starship preset <name> 之所以不需要联网下载、不依赖安装目录下的文件，是因为预设 TOML 在构建期就被嵌入了可执行文件。从源码结构看，链路如下：

1. 构建脚本 build.rs 注册了 gen_presets_hook 钩子：它扫描 docs/public/presets/toml/ 目录（cargo:rerun-if-changed 保证 TOML 变更会触发重新构建），按文件名排序后为每个 .toml 生成两个产物——预设名清单（print::Preset("...") 项）和 "名字" => include_str!(r"...toml 绝对路径") 匹配臂；
2. src/lib.rs 通过 shadow!(shadow) 宏（shadow-rs 2.0.0，见 Cargo.toml）把这些生成代码编译进二进制，shadow 模块在运行时提供 get_preset_list() 与 get_preset_content()；
3. CLI 层的 Preset 枚举实现 clap 的 ValueEnum（src/print.rs），value_variants() 直接返回 shadow::get_preset_list()。因此 starship preset --list 的输出、参数校验的合法取值，与仓库中 docs/public/presets/toml/ 下的文件一一对应；当前目录下共 12 个预设 TOML，包括本预设 no-nerd-font.toml；
4. 用户执行 starship preset no-nerd-font -o ~/.config/starship.toml 时，preset_command 取出嵌入内容并原子写盘（见前文 src/print.rs）。

这个机制还保证了文档与二进制的一致性：单元测试 preset_command_output_to_file 会把 starship preset nerd-font-symbols -o <临时文件> 的落盘内容与 include_str! 嵌入的 TOML 原文逐字节比对（src/print.rs），preset_command_output_existing_file_force 则验证了 -f 强制覆盖已存在文件的行为，preset_command_does_not_panic_on_correct_inputs 遍历所有预设名确保任何一个都不 panic。也就是说，预设内容"文档即源码"，仓库里改 TOML 即同步发布版本。

验证与应用后检查

应用预设后，可以用 Starship 自带的调试命令验证符号是否按预期渲染：

# 查看当前各模块输出、耗时与说明（能看到 battery、nodejs 等模块实际使用的符号）
starship explain

# 单独渲染某个模块，确认符号替换生效
starship module battery
starship module nodejs

explain/module 命令同样走 Context + 模块处理的渲染链路（src/print.rs 的 module 入口），输出结果反映的是 ~/.config/starship.toml 中生效的配置。预期看到的是：电池符号为 • / ⇡ / ⇣ / ❓ / ❗，Node.js 段出现加粗绿色的 ⬢，而不再是 Nerd Font 私有区符号。

如果后续想回退，直接用同样的命令换预设即可，例如 starship preset nerd-font-symbols -o ~/.config/starship.toml -f（此时需要 -f 覆盖已存在的配置文件）。

小结

• No Nerd Fonts Preset 通过覆盖 [azure]、[battery]、[erlang]、[nodejs]、[pulumi] 五个模块的符号配置，把符号集收敛到 Emoji + Powerline + 常规 Unicode 区块，实现"不装 Nerd Font 也能看全提示符"；
• 应用方式为 starship preset no-nerd-font -o ~/.config/starship.toml，-f 强制覆盖、--list 列出全部预设，行为由 src/main.rs 与 src/print.rs 定义；
• 预设内容在构建期由 build.rs 扫描 docs/public/presets/toml/ 并通过 shadow-rs 嵌入二进制，配套测试保证发布内容与仓库 TOML 逐字节一致；
• 官方已预告该预设将成为未来版本的默认预设，适合希望与未来默认行为保持一致、或终端无法安装 Nerd Font 的用户直接采用。