Starship v0.45.0 配置迁移实战：从 prompt_order 与 prefix/suffix 到统一 format 字符串

2026-09-05 09:04:21作者：沈韬淼Beryl

本文基于 Starship 官方文档《Migrating to v0.45.0》，完整讲解 Starship v0.45.0 这一含破坏性变更版本的核心配置迁移方式：如何用根级 format 字符串替代 prompt_order 数组、如何把各模块的 prefix/suffix 改为模块级 format 模板，并逐一给出受影响模块（Character、Command Duration、Directory、Environment Variable、Git Commit、Git Status、Hostname、Singularity、Time、Custom Commands）的删除属性对照表与默认配置变更。读完后，你可以把自己的旧版 starship.toml 平滑迁移到 v0.45.0+ 的格式体系，并理解其背后的格式化引擎实现。

为什么 v0.45.0 是一次破坏性升级

Starship v0.45.0 是一个包含破坏性变更的版本，官方将其作为通往稳定版 v1.0.0 的过渡：它重写了提示符的配置方式，目的是提供更大的自定义空间。在此之前，Starship 的提示符结构由两部分决定：

模块渲染顺序：由根级 prompt_order 数组指定，用户只能控制"哪些模块按什么顺序出现"，无法在模块之间插入自定义文本或装饰符；
模块内前后缀：部分模块支持 prefix 和/或 suffix，用来固定地装饰模块输出，用户无法改变"变量在字符串中的位置"。

v0.45.0 之后，这两个概念统一为一件事：format 格式字符串。根级 format 控制整个提示符的拼装，模块级 format 控制单个模块输出的拼装，变量通过 $variable 语法在模板中任意位置替换。

从源码结构看，这个"根级格式"是由提示符渲染主流程实现的：get_prompt 会读取 context.root_config，把根配置中的 format 字符串交给 load_formatter_and_modules 解析，并创建一个名为 "Starship Root" 的虚拟根模块来承载所有模块输出。值得注意的是，格式字符串中还可以写 $all——它会展开为"所有未被显式引用的模块"，这一能力在 print.rs 中可以看到对应的映射逻辑。而旧版的 prompt_order 数组则完全失去了入口，不再被解析。

配置解析本身也没有硬编码的"根配置结构体"：StarshipConfig 只是把配置文件解析为一张通用的 toml::Table，因此根级 format 本质上只是一个普通的字符串键，这解释了为什么新版格式可以写任意多行、任意嵌套的变量模板。

变更一：`prompt_order` 被根级 `format` 替代

v0.45.0 之前，prompt_order 接受一个模块名数组，按数组顺序渲染模块。

v0.45.0 之前的配置示例：

prompt_order = [
  "username",
  "hostname",
  "directory",
  "git_branch",
  "git_commit",
  "git_state",
  "git_status",
  "cmd_duration",
  "custom",
  "line_break",
  "jobs",
  "battery",
  "time",
  "character",
]

v0.45.0 的配置写法： 用同一个顺序等价改写为根级 format 字符串，其中 \ 表示续行不产生额外空格，TOML 三引号字符串保持每行对应原数组的一项：

format = """\
  $username\
  $hostname\
  $directory\
  $git_branch\
  $git_commit\
  $git_state\
  $git_status\
  $cmd_duration\
  $custom\
  $line_break\
  $jobs\
  $battery\
  $time\
  $character\
  """

迁移要点：

每个模块名 $module_name 对应旧数组中的同名元素，变量位置即渲染位置；
模块没有数据（例如不在 git 仓库中）时，对应的 $variable 会被替换为空字符串，不会留下多余空格——这一点由格式引擎的解析器保证，可参考 formatter 模块的实现；
旧 prompt_order 中未列出的模块在新格式里默认不会出现（除非引用了 $all），所以迁移时应检查是否漏写了需要的模块；
根级 format 还支持在模块之间插入字面文本、换行符 $line_break 等，这是数组写法永远做不到的。

变更二：模块 `prefix`/`suffix` 被模块级 `format` 替代

v0.45.0 之前，部分模块接受 prefix 和/或 suffix 来装饰渲染结果。v0.45.0 改为统一的 format 字符串：变量不再是"被前后缀包裹的值"，而是可以在 format 模板中任意位置替换。

v0.45.0 之前的配置示例：

[cmd_duration]
prefix = "took "

v0.45.0 的配置写法：

[cmd_duration]
# $duration – 命令执行时长（如 "15s"）
# $style    – 模块默认样式（如 "bold yellow"）
format = "took $duration "

这里还引入了 $var 的局部样式语法：变量内容被 [...] 包裹、(style) 指定样式，可以在不改变整个模块样式的前提下单独给某个变量着色。

下面按模块逐一列出删除的属性及其替代方案，并附官方默认配置的变更 diff。迁移时对照这些默认值，可以把旧配置逐项翻译过去。

Character 模块

删除的属性	替代属性
`symbol`	`success_symbol`
`use_symbol_for_status`	`error_symbol`
`style_success`	`success_symbol`
`style_failure`	`error_symbol`

默认配置变更：

[character]
-- symbol = "❯"
-- error_symbol = "✖"
-- use_symbol_for_status = true
-- vicmd_symbol = "❮"
++ success_symbol = "❯"
++ error_symbol = "❯"
++ vicmd_symbol = "❮"

行为变化说明：

旧版中 use_symbol_for_status 控制"上一条命令返回非零状态码时是否显示 error_symbol"；v0.45.0 起，非零状态码后始终使用 error_symbol，即 use_symbol_for_status 与 error_symbol 两个属性被合并为一个；
想要复刻旧版 use_symbol_for_status = true 的效果（成功显示 ❯、失败显示 ✖），在配置文件中加入：

[character]
error_symbol = "✖"

注意：character 模块会自动在其后追加一个空格，因此与上面其他模块的 format 不同，其默认值刻意不在结尾加空格。

源码佐证：src/configs/character.rs 中 CharacterConfig 定义了 success_symbol、error_symbol 等字段，默认值正是 ❯ 与 ❯，与文档中的新默认配置一致。

Command Duration 模块

删除的属性	替代属性
`prefix`	`format`

默认配置变更：

[cmd_duration]
-- prefix = "took "
++ format = "took $duration "

Directory 模块

删除的属性	替代属性
`prefix`	`format`

默认配置变更：

[directory]
-- prefix = "in "
++ format = "$path$read_only "

可以看到新默认格式中 $read_only 变量与独立的 $read_only_style 样式也被纳入模板，只读目录的装饰不再依赖固定前后缀。

Environment Variable 模块

删除的属性	替代属性
`prefix`	`format`
`suffix`	`format`

默认配置变更：

[env_var]
-- prefix = ""
-- suffix = ""
++ format = "with $env_value "

Git Commit 模块

删除的属性	替代属性
`prefix`	`format`
`suffix`	`format`

默认配置变更：

[git_commit]
-- prefix = "("
-- suffix = ")"
++ format = '\($hash\) '

注意 TOML 单引号字符串中的 \$：\$hash 会被解析为带字面括号的 ($hash)，括号成为模板的一部分而不是格式语法。

Git Status 模块

删除的属性	替代属性
`prefix`	`format`
`suffix`	`format`
`show_sync_count`	`format`

默认配置变更：

[git_status]
-- prefix = "["
-- suffix = "]"
-- show_sync_count = false
++ format = '([\[$all_status$ahead_behind\]]($style) )'

行为变化说明：

旧版 show_sync_count 用来配置"是否显示分支领先/落后远程分支的提交数"；v0.45.0 将其替换为三个独立属性 ahead、behind、diverged，各自是一段格式字符串，粒度更细；
要复刻旧版 show_sync_count = true 的显示效果，在配置文件中设置：

[git_status]
ahead = "⇡${count}"
diverged = "⇕⇡${ahead_count}⇣${behind_count}"
behind = "⇣${count}"

源码佐证：src/configs/git_status.rs 中默认值即为 format: "([\[$all_status$ahead_behind\]]($style) )"、ahead: "⇡"、behind: "⇣"、diverged: "⇕"，与文档 diff 完全对应。

Hostname 模块

删除的属性	替代属性
`prefix`	`format`
`suffix`	`format`

默认配置变更：

[hostname]
-- prefix = ""
-- suffix = ""
++ format = "$hostname in "

Singularity 模块

删除的属性	替代属性
`label`	`format`
`prefix`	`format`
`suffix`	`format`

默认配置变更：

[singularity]
-- prefix = ""
-- suffix = ""
++ format = '[$symbol\[$env\]]($style) '

源码佐证：src/configs/singularity.rs 中 SingularityConfig::default() 的 format 默认值就是 [$symbol\[$env\]]($style) ，其中 label 属性的显示职责由模板中的 [$env] 部分接管。

Time 模块

删除的属性	替代属性
`format`	`time_format`

默认配置变更：

[time]
-- format = "🕙[ %T ]"
++ time_format = "%T"
++ format = "at 🕙$time "

这是唯一一处"属性名让位"的变更：旧版 format 里混着"时钟图标 + 时间格式串"，新版把** strftime 格式串**独立成 time_format（在 src/configs/time.rs 中为 Option<&str>，None 表示使用平台默认格式），而 format 恢复为统一的模块模板字符串。

Custom Commands 模块

删除的属性	替代属性
`prefix`	`format`
`suffix`	`format`

默认配置变更：

[custom.example]
-- prefix = ""
-- suffix = ""
++ format = "$symbol$output "

自定义命令模块（[custom.xxx] 配置段）的输出变量 $output 同样进入模板体系，symbol 也可以由用户配置。

迁移清单与注意事项

综合上述变更，迁移一份旧版 starship.toml 的操作步骤是：

删除根级 prompt_order，按原数组顺序改写为根级 format 多行字符串（见"变更一"示例）；
逐模块检查 prefix/suffix 属性，按上表翻译为模块级 format，把原前后缀文本放入模板相应位置；
Character 模块单独处理：symbol → success_symbol，并按需设置 error_symbol = "✖" 复刻旧的失败符号行为；
Git Status 若曾使用 show_sync_count = true，改为显式配置 ahead/behind/diverged 三行字符串；
Time 模块若自定义过 format，把其中的 strftime 部分（如 %T）移到 time_format；
迁移后建议运行 starship config 或观察提示符输出确认各模块渲染符合预期——提示符最终输出统一由 get_prompt 拼装，各模块的默认值定义集中在 src/configs 目录下（每个模块一个文件，如 character.rs、git_status.rs、time.rs），遇到不确定的默认值可直接对照源码。