Starship 预设（Presets）完全使用指南：从官方收录的社区配置到一键应用与二次定制

本文以 Starship 官方文档中的「Presets（预设）」目录（含中文、波兰语等本地化版本，本仓库中对应 docs/pl-PL/presets/README.md 等文件）为线索，系统讲解预设的定义、应用原理、12 款官方收录社区配置各自的特征与适用场景，以及如何以仓库内的 TOML 与源码为依据验证和扩展自己的配置。读完你将能够独立完成预设的安装、覆盖写入、效果核验，并理解预设与 starship preset 命令的底层实现关系。

预设（Preset）是什么，以及官方目录放在哪里

在 Starship 中，"预设"是一份已经调好格式与配色、面向某种特定风格或使用场景的完整 TOML 配置。它不同于需要手工逐段编写的原生配置，而是社区贡献、官方评审收录后随仓库一起维护的现成方案。你可以直接把它整份应用到自己的 starship.toml 中，不必理解每一个选项也能立刻获得对应的提示符外观。

官方预设的"总目录"就是 docs/presets/README.md：它列出每款预设的一句话简介、一幅真实运行截图，以及指向各预设详细页的链接。这份目录随 Starship 一起被翻译成多种语言，本仓库的波兰语版即 docs/pl-PL/presets/README.md，目录内每个预设的详细页（如 docs/pl-PL/presets/bracketed-segments.md）也一一对应存在。各语言版目录的结构完全一致：点击截图或标题，即可进入该预设的使用说明。

每一款预设都包含三类配套资源，全部位于仓库固定目录：

• 详细说明页：docs/presets/<预设名>.md（含应用命令与截图）；
• 可下载的配置本体：docs/public/presets/toml/<预设名>.toml；
• 运行效果截图：docs/public/presets/img/<预设名>.png。

例如目录中的 Nerd Font Symbols 对应 nerd-font-symbols.toml 与 nerd-font-symbols.png。这些 TOML 不是摆设——starship preset 命令实际输出的内容与之严格一致（下文详述）。

底层原理：starship preset 命令是怎么把预设"发"给你的

从源码看，预设功能是 Starship CLI 的一个子命令。在 src/main.rs 中可以看到 preset 子命令的选项说明：它接收"要打印的预设名称"、支持"把预设输出到文件而不是标准输出"，并提供"列出全部预设名称"的能力；实际分发执行发生在 src/main.rs 处的 print::preset_command(name, output, force, list)。

命令的真正实现在 src/print.rs 的 preset_command 函数中：

1. 当请求列出预设时，调用 preset_list() 输出名称清单（实现在 src/print.rs）；
2. 否则通过 shadow::get_preset_content(...) 取出对应预设的 TOML 文本；
3. 若指定了 -o/--output 目标文件则写入该文件，否则打印到标准输出。

仓库中的单元测试还直接印证了"TOML 源文件即输出基准"这一事实：例如 src/print.rs 的测试使用 include_str!("../docs/public/presets/toml/nerd-font-symbols.toml") 与命令实际输出逐字比对，src/print.rs 的测试则断言 preset_list() 至少能列出 1 个预设，且对每一个预设名调用命令都不会 panic（src/print.rs）。这意味着：想确认某款预设到底改了什么，直接阅读 docs/public/presets/toml/ 下的同名 TOML 文件就是最权威的依据。

快速上手：查看、应用与覆盖写入

应用预设最推荐的方式是让命令直接把配置写到 Starship 的配置文件（默认位置为 ~/.config/starship.toml）。以 Pure 预设为例，先不带输出参数预览内容：

starship preset pure-preset

确认无误后写入配置：

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

命令本身支持将预设输出到任意文件（-o），并且对已存在文件的覆盖、以及"列出全部可用预设名称"等行为，可在运行时通过 starship preset --help 查看确认。两点实用提醒：

• 写入即整份覆盖：-o 指向的配置文件会被预设内容整体替换。若你已有大量自定义，建议先备份现有配置，或把 starship preset <name> 打印出的内容手动合并进原文件的相应段落，实现"局部采用某预设的风格片段"。
• 无需编译：预设只是 TOML 文本。应用后新开一个终端窗口（或按所用 Shell 的机制重新加载）即可看到效果；不喜欢时把配置文件还原/删除即恢复默认提示符。

官方收录的 12 款预设逐项解析

下面按官方目录顺序逐一说明每款预设的特征、适用场景与应用命令。命令中的预设名均与该预设的 TOML 文件名一一对应（可在 docs/public/presets/toml/ 目录核对）。

1. Nerd Font Symbols —— 让每个模块用上 Nerd Font 符号

这款预设把各模块的符号统一替换为 Nerd Font 字形，追求符号的丰富与一致（如分支、图标类符号）。它要求终端里已安装并启用一款 Nerd Font，官方示例使用 Fira Code Nerd Font。

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

详细页：docs/presets/nerd-font.md；配置本体：nerd-font-symbols.toml。

2. No Nerd Fonts —— 完全没有 Nerd Font 也能完整显示

与上一款正好相反：它把多个模块的符号收敛为 emoji 与 Powerline 符号集，从而即使终端没有安装 Nerd Font，提示符中所有模块符号也能正常渲染。其 TOML 中可以看到大量 emoji 式的替换，例如 [azure] 使用 "☁️ "、[pulumi] 使用 "🧊 "、[nodejs] 使用 "⬢ " 等（见 no-nerd-font.toml）。

值得关注的是，官方目录中以提示（TIP）形式注明：该预设计划在未来版本中成为 Starship 的默认预设，因此它也被视为"低依赖、跨环境稳妥"的代表。

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

详细页：docs/presets/no-nerd-font.md。

3. Bracketed Segments —— 用方括号替代 "via / on" 连接词

Starship 内置模块在显示时默认会出现 via、on 等连接性文字。这款预设把所有内置模块的段落格式改为方括号包裹的分段样式，观感更紧凑、结构更清晰，是喜欢"信息分块"风格的用户的常用选择。

starship preset bracketed-segments -o ~/.config/starship.toml

详细页：docs/presets/bracketed-segments.md；配置本体：bracketed-segments.toml。

4. Plain Text Symbols —— 纯 ASCII 符号，告别 Unicode 依赖

把各模块的符号全部换成纯文本表达。对于身处不支持 Unicode 的终端、远程环境或某些嵌入式/串口场景的用户，它是保证提示符不出现"乱码方块"的实用兜底方案。

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

详细页：docs/presets/plain-text.md；配置本体：plain-text-symbols.toml。

5. No Runtime Versions —— 隐藏各语言运行时版本号

预设会关闭/隐藏语言运行时（如 Python、Node.js 等）的版本显示。如果你经常工作在容器、虚拟化或共享开发机中，版本号既无意义又占空间，这款预设正好对症。

starship preset no-runtime-versions -o ~/.config/starship.toml

详细页与配置：目录对应 no-runtime-versions 一栏；TOML 见 no-runtime-versions.toml。

6. No Empty Icons —— 工具没检测到就不显示图标

Starship 的许多模块在"当前目录存在某工具/项目"时才显示对应图标。这款预设保证当工具集未被检测到时，不输出空白图标，避免提示符中出现"悬空"的孤立符号，让显示始终干净有意义。

starship preset no-empty-icons -o ~/.config/starship.toml

详细页与配置：目录对应 No Empty Icons 一栏；TOML 见 no-empty-icons.toml。

7. Pure Prompt（pure-preset）—— 复刻 Pure 的极简体验

这款预设模拟经典 Pure 提示符的观感与行为：极少的模块、清晰的颜色区分。从它的配置可见其"瘦身"思路——顶层 format 只保留用户名、主机名、目录、Git 分支/状态/变化、命令耗时与 Python 虚拟环境等少数关键模块（见 pure-preset.toml）：

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

[directory]
style = "blue"

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

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

[python]
format = "$virtualenv "
style = "bright-black"

这里能直观看到预设与 TOML 的对应关系：紫色的成功符 ❯、红色的出错符 ❯、绿色的 vim 模式符 ❮，正是 Pure 风格在 Starship 配置层（[character] 段）的落地表达。

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

详细页：docs/presets/pure-preset.md。

8. Pastel Powerline —— 粉彩 Powerline + 路径替换演示

这款预设受 oh-my-posh 的 M365Princess 主题启发，采用 Powerline 风格的区块衔接与粉彩配色。官方目录还特别提示：它同时示范了 Starship 的路径替换（path substitution）能力——即把工作目录中的长路径按规则替换为短别名显示，适合想学习 [directory] 段 repos/truncate 等路径处理技巧的读者。

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

详细页与配置：目录对应 Pastel Powerline 一栏；TOML 见 pastel-powerline.toml。

9. Tokyo Night —— VS Code 同款暗夜配色

配色灵感来自广受欢迎的 tokyo-night VS Code 主题，把提示符整体色调调成深邃蓝紫的夜景风，适合与该主题的编辑器、终端配色组成统一视觉体系。

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

详细页与配置：目录对应 Tokyo Night 一栏；TOML 见 tokyo-night.toml。

10. Gruvbox Rainbow —— Pastel Powerline × Tokyo Night 的融合

官方介绍其为"重度受 Pastel Powerline 与 Tokyo Night 启发"的产物，兼具 Powerline 的块状结构与暖色/彩虹渐变般的分组着色，是复古暖色调爱好者的常选。

starship preset gruvbox-rainbow -o ~/.config/starship.toml

详细页与配置：目录对应 Gruvbox Rainbow 一栏；TOML 见 gruvbox-rainbow.toml。

11. Jetpack —— 受 geometry 与 spaceship 启发的"伪极简"

如其名，这是受 geometry 与 spaceship 两款知名提示符启发设计的伪极简预设：整体信息保持精简，但保留必要的上下文提示，适合既想要干净又不想牺牲信息量的用户。

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

详细页与配置：目录对应 Jetpack 一栏；TOML 见 jetpack.toml。

12. Catppuccin Powerline —— Gruvbox Rainbow 的 Catppuccin 换色版

在 Gruvbox Rainbow 基础上仅做"最小修改"——整体换成 Catppuccin 主题的柔和粉彩调色板，结构与 Gruvbox Rainbow 保持一致、配色更柔和，适合 Catppuccin 生态用户。

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

详细页与配置：目录对应 Catppuccin Powerline 一栏；TOML 见 catppuccin-powerline.toml。

进阶：如何基于预设做二次定制，或投稿自己的预设

二次定制：预设本质上就是一份普通 TOML 配置，没有任何"魔法"。应用预设后，你可以继续编辑 starship.toml 覆盖其中任意字段——例如保留 Pure 的 format 骨架，但把 [character] 的成功符改成自己喜欢的字形与颜色。修改粒度、字段名与默认值均以官方配置文档为准（可参考仓库中的 docs/config/README.md 及各模块配置说明，如 docs/config/README.md 中对 character、directory 等段的逐项解释）。

投稿新预设：官方目录首页明确欢迎社区贡献——将自己的预设通过 PR 更新到预设目录文件中。结合仓库现有结构（docs/presets/<name>.md 说明页 + docs/public/presets/toml/<name>.toml 配置 + docs/public/presets/img/<name>.png 截图 + 在 docs/presets/README.md 中登记条目），可以推断一个规范的投稿大致需要补齐上述四类文件，并在各语言目录（如 docs/pl-PL/presets/README.md）同步登记对应翻译条目，从而让全球用户在同一个入口找到并一键应用你的配置。

小结

• 怎么看：预设总目录在 docs/presets/README.md，波兰语等本地化版本位于 docs/pl-PL/presets/README.md 及各语言同名目录。
• 怎么装：starship preset <预设名> -o ~/.config/starship.toml，一行命令完成整份替换；不想覆盖时可先把输出打印出来人工合并。
• 怎么验证：命令输出与 docs/public/presets/toml 下的源 TOML 逐字一致（由 src/print.rs 的测试用 include_str! 保证）；想研究具体改了什么，直接读对应 TOML 文件即可。
• 怎么扩展：预设只是普通 TOML，可被后续编辑自由覆盖；新方案可参照既定目录结构整理后通过 PR 收录进官方目录。

无论你是追求零字体依赖的跨环境稳妥、极简 Purity、Powerline 块状美感，还是想要一套与编辑器同源的配色，这 12 款官方收录预设都提供了一条"拿来即用"的捷径。