Starship Presets 预置配置完整指南：从社区主题库到一键式 prompt 定制

Starship 内置了一套由社区贡献、仓库统一收录的**预置配置（Presets）**体系：每一种 Preset 都是一份完整的 starship.toml 配置文件，可以一键覆盖你当前的 prompt 外观与信息密度，从"Nerd Font 图标集""纯文本符号"到"Pure 风格""Powerline 彩虹主题"一应俱全。本文以仓库的 docs/presets/README.md 索引为骨架，逐一讲解 12 款官方收录预置的使用前提、安装命令与核心配置思路，并结合 src/print.rs 等源码说明 starship preset 命令的底层工作机制，帮助你在几秒钟内换装 prompt，也能在此基础上继续深度定制。

Presets 是什么：文档索引与仓库资源对照

在 Starship 仓库中，预置配置被组织为一个独立的文档目录：

• 总览索引：docs/presets/README.md，按图片/描述列出全部社区预置，并明确标注"点击图片即可查看对应预置的详细用法"；
• 每个预置的独立说明页：例如 docs/presets/nerd-font.md、docs/presets/pure-preset.md 等 12 个 Markdown 文件；
• 每个预置的完整配置成品（TOML）：统一存放在 docs/public/presets/toml/ 目录下（共 12 份），也就是每页说明中嵌入展示的那份配置；
• 对应的预览截图：存放在 docs/public/presets/img/。

从这份索引的组织方式可以看出：Preset 的本质就是一份可以直接写入 ~/.config/starship.toml 的完整 TOML 配置。官方仓库以"文档索引 + 完整 TOML + 预览截图"三件套的形式维护这些预置，方便用户在可视化预览后快速采纳。

按解决的问题，12 款预置大致可分为三类：

类别	预置	解决的核心问题
符号 / 字体	Nerd Font Symbols、No Nerd Fonts、Plain Text Symbols	prompt 中图标的字体依赖与可读性
内容 / 格式	Bracketed Segments、No Runtime Versions、No Empty Icons	信息段的表达形式与"何时显示"
完整主题	Pure Prompt、Pastel Powerline、Tokyo Night、Gruvbox Rainbow、Jetpack、Catppuccin Powerline	整体配色、布局与视觉风格

快速上手：用一条命令应用任意 Preset

所有预置说明页给出的安装方式都统一为一条命令，例如以 Nerd Font Symbols 为例：

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

把其中的 nerd-font-symbols 换成其他预置名（如 no-nerd-font、pure-preset、catppuccin-powerline）即可一键换装。该命令的作用是：把内置的对应预置配置写入你指定的输出文件，默认会覆盖原有的 ~/.config/starship.toml。

命令可选项与覆盖行为

从命令行入口源码看，preset 子命令被解析为一组参数（参见 src/main.rs 中的注释性文档）：

• 需要一个预置名，例如 pure-preset；
• 支持"输出到文件"选项（即上文 -o ~/.config/starship.toml 的由来，源码注释为 "Output the preset to a file instead of stdout"）；
• 提供 force 开关，用于在目标文件已存在时允许覆盖写入；
• 提供 list 开关，用于把所有可用的预置名列出来（对应源码注释 "List out all preset names"）。

处理逻辑会集中分派到 src/print.rs 的 preset_command 函数，随后输出到 stdout 或指定文件。需要指出的是：在实现层，各预置的 TOML 文本是被内置读取的（同一函数内通过 shadow 模块读取内容），也就是说你并不需要从网上额外下载任何文件，二进制内已经携带了全部 12 份预置。

一份预置文件总是以 $schema 声明开头，例如 Nerd Font Symbols 的第一行：

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

该行用于让编辑器对配置文件做实时校验；仓库根目录也同步维护了 schema 实体文件 docs/public/config-schema.json。写入并重新加载 shell 配置后即可生效。

动手之前建议先阅读仓库的 docs/installing/README.md 完成 Starship 安装与 shell 初始化；若你在纠结配置写在哪、模块怎么写，可参考 docs/config/README.md 与 docs/advanced-config/README.md。

符号 / 字体类预置

这一类预置不改动 prompt 的布局，只替换各模块的图标来源，用于解决"图标能不能显示出来"这个最基础也最影响观感的问题。

Nerd Font Symbols：为每个模块换上 Nerd Font 图标

说明页：docs/presets/nerd-font.md｜完整配置：docs/public/presets/toml/nerd-font-symbols.toml

这是最经典的"全家桶"图标方案：把几乎所有内置模块的 symbol 都替换为 Nerd Font 字形（该文档示例推荐配合 Fira Code Nerd Font 使用）。

前提条件：终端中需要安装并启用一款 Nerd Font 字体。

配置核心非常简单——基本只有两个键，一是模块图标：

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

[git_branch]
symbol = " "

[rust]
symbol = "󱘗 "

[package]
symbol = "󰏗 "

二是针对操作系统这类"按值映射"的模块提供整套图标映射表 [os.symbols]。原文件为该表一次性声明了数十个发行版 / 系统的图标（如 Arch = " "、Ubuntu = " "、Windows = "󰍲 "、Macos = " "、Debian = " " 等），这就是该文件篇幅较长（完整见 docs/public/presets/toml/nerd-font-symbols.toml，约 300 行）的主要原因——它覆盖了 src/configs/ 下几乎每个模块的 symbol 字段。

No Nerd Fonts：完全不依赖 Nerd Font

说明页：docs/presets/no-nerd-font.md｜完整配置：docs/public/presets/toml/no-nerd-font.toml

这个预置将各模块符号限制在 emoji 与 powerline 字符集 内，从而在未安装 Nerd Font 的终端中也能完整显示全部模块图标。文档中特别标注：该预置计划在未来的某个 Starship 版本中成为默认预置。

应用命令：

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

其核心替换如下（节选）：

[azure]
symbol = "☁️ "

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

[nodejs]
symbol = "⬢ "

[pulumi]
symbol = "🧊 "

注意 [nodejs] 的写法：symbol 不仅可以是一个字符，还可以是一条带样式声明的字符串 "⬢ "——这也侧面印证了 Starship 的 symbol 字段本身就支持 style code 内联语法。

Plain Text Symbols：纯文本符号

说明页：docs/presets/plain-text.md｜完整配置：docs/public/presets/toml/plain-text-symbols.toml

当你的环境完全不支持 Unicode（例如某些老式终端、远程串口等极端场景）时，该预置把所有模块图标换成纯 ASCII 文本，代价最小地保住 prompt 的信息可读性。应用方式同样是一条命令：

starship preset plain-text-symbols -o ~/.config/starship.toml

它与 No Nerd Fonts 的区别在于：前者只规避 Nerd Font 专有字形（仍允许 emoji），而后者彻底回归纯文本，二者适用的终端能力等级不同，可按环境取舍。

内容与格式类预置

这一类预置聚焦 prompt 的"信息组织方式"：版本号要不要显示、图标什么时候出现、模块如何被分隔。

Bracketed Segments：模块统一加方括号

说明页：docs/presets/bracketed-segments.md｜完整配置：docs/public/presets/toml/bracketed-segments.toml

默认情况下 Starship 的不同模块之间靠 via、on、with 等连词区分语义（例如 "via rustc"）。Bracketed Segments 的做法是：改写所有内置模块的 format，让每个模块的内容落在方括号内，使段落边界更清晰。核心配置形如：

[aws]
format = '\[[$symbol($profile)(\($region\))(\[$duration\])]($style)\]'

[battery]
format = '\[$symbol$percentage\]'

[cmd_duration]
format = '\[⏱ $duration\]'

[c]
format = '\[$symbol($version(-$name))\]'

注意其中 \[ 与 \] 是转义后的字面方括号字符，它们不属于样式语法而是"真实打印出来的括号"；整个文件遍历了 aws、azure、battery、c、cmake、cmd_duration 等几乎所有内置模块（完整见 docs/public/presets/toml/bracketed-segments.toml），因此一份配置即可统一全局观感。如果你希望 prompt 中各段边界一目了然、且不喜欢英语连词，这一款是低成本高收益的选择。

No Runtime Versions：隐藏运行时版本号

说明页：docs/presets/no-runtimes.md｜完整配置：docs/public/presets/toml/no-runtime-versions.toml

默认的运行时模块（语言、构建工具）会同时显示图标与版本号。若你在容器、虚拟机或版本频繁切换的虚拟化环境中工作，版本号可能毫无意义甚至造成误导。该预置把各语言模块的 format 精简为只保留图标与模块名：

[bun]
format = "via $symbol"

[c]
format = "via $symbol($name)"

[dotnet]
format = "$symbol(🎯 $tfm )"

[golang]
format = 'via $symbol'

对比默认行为即可看出本质：($version) 这类圆括号括起的可选项从 format 中删除，版本检测逻辑仍然存在但不再渲染；dotnet 仍保留 $tfm（目标框架）等有实际判别价值的字段。源码层面，每个模块 format 中 (...) 为可选分组，若组内变量为空则该组整段不输出——这正是"删掉版本组即隐藏版本"能够成立的机制基础。若你的工作流需要更小的横向空间、更少噪音，此预置尤其适合。

No Empty Icons：只在能拿到版本信息时才显示图标

说明页：docs/presets/no-empty-icons.md｜完整配置：docs/public/presets/toml/no-empty-icons.toml

默认行为下，只要识别到了工具链相关文件（例如检测到 package.json），Starship 就会显示对应模块的图标，即使该工具本身尚未安装、版本无法确定。No Empty Icons 改变了这个逻辑：只有当能确定工具集版本时，才让图标出现。

它的实现非常巧妙，是把图标与版本一起放进可选分组，例如：

[buf]
format = '(with $symbol($version ))'

[bun]
format = '(via $symbol($version ))'

[c]
format = '(via $symbol($version(-$name) ))'

[elixir]
format = '(via $symbol($version \(OTP $otp_version\) ))'

原理是：当 $version 取不到值（工具未安装）时，(via $symbol($version )) 这整个可选组都不渲染，于是图标自然消失；反之工具可用时图标、版本一次性出现。这对于"避免 prompt 中出现一堆装不上工具的幽灵图标"非常实用。若想观察两种行为差异，可直接使用 docs/public/presets/img/no-empty-icons.png 处的官方预览图对比效果。

完整视觉主题类预置

Pure Prompt：复刻 zsh Pure 的外观与行为

说明页：docs/presets/pure-preset.md｜完整配置：docs/public/presets/toml/pure-preset.toml

该预置在 Starship 中复刻知名 zsh 提示符 Pure 的极简风格：顶部一行信息、底部仅一个提示符光标。应用命令：

starship preset pure-preset -o ~/.config/starship.toml

关键配置如下（节选）：

format = """
$username\
$hostname\
$directory\
$git_branch\
$git_state\
$git_status\
$cmd_duration\
$line_break\
$python\
$character"""

[character]
success_symbol = "❯"
error_symbol = "❯"
vimcmd_symbol = "❮"

[git_branch]
format = "$branch"
style = "bright-black"

[cmd_duration]
format = "$duration "
style = "yellow"

从 format 可读出 Pure 的布局哲学：常规信息全部集中在提示符上方（目录、git 分支/状态、上条命令耗时），$line_break 之后仅保留一个 $character 光标；同时 success_symbol/error_symbol/vimcmd_symbol 让光标随退出码与 vim 模式变色。值得一提的是，该预置把所有"占位却不可见"的 git 状态变量都设为不可见占位符，避免多余空格。整体预览可参考 docs/public/presets/img/pure-preset.png。

Pastel Powerline：Powerline 风格的路径替换范例

说明页：docs/presets/pastel-powerline.md｜完整配置：docs/public/presets/toml/pastel-powerline.toml

Pastel Powerline 是一套粉彩配色的 Powerline 主题（灵感来自 M365Princess 风格），更重要的是，官方文档特别指出它顺带演示了 Starship 的路径替换（path substitution）机制。应用方式：

starship preset pastel-powerline -o ~/.config/starship.toml

布局上采用自绘的多色分段：每一段都是一个样式不同的分组，段与段之间用 powerline 三角字符  衔接并声明前后两段的 fg/bg，从而产生无缝斜切过渡：

format = """
[](#9A348E)\
$os\
$username\
\
$directory\
\
$git_branch\
$git_status\
...
 \
"""

[directory]
style = "bg:#DA627D"
format = " $path "
truncation_length = 3
truncation_symbol = "…/"

真正的亮点在 [directory.substitutions]：它可以把路径中的长单词替换为短文本或图标，行为类似 Oh My Posh 的 mapped_locations：

[directory.substitutions]
"Documents" = "󰈙 "
"Downloads" = " "
"Music" = " "
"Pictures" = " "

配置中的注释还点出了一个重要陷阱：替换顺序敏感。例如 "Important Documents" 若排在 "Documents" 之后则永远不会被命中（因为 "Documents" 已经先被替换掉了）；解决办法是把更长的目标写在前面，或直接对被替换后的结果再替换。该机制的模块级默认字段可对照 directory 模块配置 理解。预览效果见 docs/public/presets/img/pastel-powerline.png。

Tokyo Night：东京夜主题配色

说明页：docs/presets/tokyo-night.md｜完整配置：docs/public/presets/toml/tokyo-night.toml

该预置移植了广受欢迎的 tokyo-night-vscode-theme 配色，深蓝紫为主的暗色系适用于多数暗色终端。同样需要先安装 Nerd Font（其完整 TOML 见 docs/public/presets/toml/tokyo-night.toml，内嵌了调色板定义与各模块的 style 映射）。应用命令与其他主题一致：

starship preset tokyo-night -o ~/.config/starship.toml

Gruvbox Rainbow：源自前两者的"彩虹混血"

说明页：docs/presets/gruvbox-rainbow.md｜完整配置：docs/public/presets/toml/gruvbox-rainbow.toml

文档明确说明，Gruvbox Rainbow 大量借鉴了 Pastel Powerline 与 Tokyo Night：保留了 Pastel Powerline 的"语言模块按彩虹色渐变分段"结构，同时换上 Gruvbox 的暖色系调色板。整体思路同样以 format 中连续分段的 bg/fg 色带实现。若你在 Gruvbox 风格的编辑器与终端里工作，这款能形成配色呼应。

Jetpack：极简伪简约 + 右提示符示范

说明页：docs/presets/jetpack.md｜完整配置：docs/public/presets/toml/jetpack.toml

Jetpack 是一款"伪极简"预置：左侧提示符极其精简（只保留容器、git 状态、耗时、用户名与光标等），而把大部分工具链信息搬到右侧提示符，由右向左展开。文档强调 Jetpack 会使用终端自身的配色主题，因此它不依赖某个固定调色板，能自然融入你的终端配色。

前置条件（注意，这两条与多数预置不同）：

• 需要你的 shell 支持 right-prompt（右提示符）；仓库在 docs/advanced-config/README.md 中说明了 right_format 的启用方式与支持范围；
• 推荐使用 JetBrains Mono 字体（它不是 Nerd Font 系）。

关键结构（节选）：

format = """($nix_shell$container$fill$git_metrics\n)$cmd_duration\
$hostname\
$localip\
$shlvl\
$shell\
$env_var\
$jobs\
$sudo\
$username\
$character"""

right_format = """
$singularity\
$kubernetes\
$directory\
$git_branch\
$git_commit\
$git_state\
$git_status\
...
"""

$fill 模块把左右两侧分隔开、\n 前的分组实现了"上下文信息单独一行"的效果，而 right_format 承担了语言/工具链模块的展示——这本身就是一个学习"如何用 format + right_format 规划双栏 prompt"的绝佳模板。完整文件见 docs/public/presets/toml/jetpack.toml。

Catppuccin Powerline：四口味切换的 Powerline 主题

说明页：docs/presets/catppuccin-powerline.md｜完整配置：docs/public/presets/toml/catppuccin-powerline.toml

Catppuccin Powerline 是对 Gruvbox Rainbow 的最小化修改版：结构几乎不变，仅将调色板整体替换为 Catppuccin。默认使用 Mocha 风味，且通过顶层 palette 字段切换：

format = """
\
$os\
$username\
\
$directory\
...
"""

palette = 'catppuccin_mocha'

根据说明页，你只需修改 palette 的值即可在四种风味间切换：

• catppuccin_mocha
• catppuccin_frappe
• catppuccin_macchiato
• catppuccin_latte

其中 style 里出现的 red、peach、green、sapphire、lavender 等颜色名均来自文件中定义好的 Catppuccin 调色板（颜色名到具体色值的映射在调色板段内完成），这种"调色板 + 具名色"的写法也正是 Starship palette 机制的核心用法。若你已是 Catppuccin 用户，它能在终端各处保持完全一致的色彩语言。

源码视角：preset 命令是如何工作的

把文档层的操作与实现层的代码对照起来，可以更清楚地理解整条链路：

1. CLI 解析：preset 作为 Starship 的一个子命令出现在参数结构中，带预置名、输出文件、覆盖开关与列出开关等字段，注释见 src/main.rs；
2. 分发执行：命令行解析后调用 src/print.rs 的 preset_command——当用户传入 --list 时打印全部预置名，否则读取内置预置内容并输出到 stdout 或 -o 指定的文件；
3. 内容来源：所有预置 TOML 都在二进制构建时被内置（print.rs 中通过 shadow 模块的 get_preset_content 获取），仓库里的 docs/public/presets/toml/ 就是这些内容的上游源文件，两者一一对应；
4. 质量保障：print.rs 中附带了相应测试（例如校验列表非空、每个预置输出不 panic、输出到文件、已存在文件配合 force 覆盖等场景，见 src/print.rs），保证每个内置预置都能被稳定输出。

这意味着：即使离线、不访问任何网站，starship preset xxx -o ~/.config/starship.toml 也能完整落地一份经过测试的配置。

写在最后：如何选型与继续定制

选型可以按你的实际约束快速决策：

• 终端没装 / 不想装 Nerd Font：直接选 no-nerd-font（emoji 兼容）或 plain-text-symbols（纯 ASCII）；
• 图标显示异常但想用图标：安装 Nerd Font 后用 nerd-font-symbols；
• 在容器 / CI / 虚拟机里工作：no-runtime-versions 避免版本噪音；
• 不想看到"幽灵图标"：no-empty-icons 只在工具确实可用时显示；
• 追求极简单行或双栏布局：pure-preset（单栏极简）、jetpack（左简右繁，需 right-prompt 支持）；
• 想要完整视觉主题：在 pastel-powerline、tokyo-night、gruvbox-rainbow、catppuccin-powerline 之间按调色板口味选择（后两者分别可改 palette / 继承自前者）。

预置本质只是"一份合格配置的起点"。应用后你随时可以继续手工编辑 ~/.config/starship.toml：模块级参数的完整说明在 docs/config/README.md，涉及 right_format、palette、格式串高级语法等进阶主题参考 docs/advanced-config/README.md；所有内置模块的默认字段与取值可在 src/configs/ 目录（如 directory.rs、git_branch.rs）中逐一核对，作为自定义时的对照基准。理解每份预置"改了哪些字段、为什么这样改"，你就能从"换皮肤"进阶到"按需定制属于自己的 Starship"。