Starship v0.45.0 迁移指南：从 prompt_order 与 prefix/suffix 全面转向 format 字符串

Starship v0.45.0 是该项目为 v1.0.0 正式版做铺垫的重要版本，它引入了两项破坏性变更：根级 prompt_order 被 format 取代，模块级 prefix/suffix 被模块级 format 取代。本文完整覆盖官方迁移文档（docs/bn-BD/migrating-to-0.45.0/README.md，其内容与英文原文档 docs/migrating-to-0.45.0/README.md 一致）中的全部配置改写对照，并结合当前仓库源码逐条印证新的 format 解析机制与受影响模块的实现，帮助你将旧版 Starship 配置平滑升级到 0.45.0 及之后的版本。

v0.45.0 为什么要做破坏性变更

官方文档开宗明义：v0.45.0 包含破坏性变更，目的是为 v1.0.0 做准备。核心动机是重构提示符的配置方式，以获得更高的自定义自由度——旧方案只能控制"哪些模块按什么顺序出现"以及"模块前后各加什么文字"，新方案则允许在模块体系之外自由编排提示符，并让每个模块的输出成为可组合、可着色的格式串。

prompt_order 被根级 format 取代

在 v0.45.0 之前，prompt_order 接受一个模块名数组，按数组顺序渲染各模块。v0.45.0 改为接受根级 format 值，允许对模块本身之外的提示符部分进行自定义。

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 = """\
  $username\
  $hostname\
  $directory\
  $git_branch\
  $git_commit\
  $git_state\
  $git_status\
  $cmd_duration\
  $custom\
  $line_break\
  $jobs\
  $battery\
  $time\
  $character\
  """

迁移要点：

• 每个模块名变成 $模块名 变量（如 $username），按书写顺序渲染；
• 多行 TOML 字符串中每行末尾的 \ 是 TOML 的续行转义，用于保留模块间的原始衔接（避免引入多余空格）；
• 由于 format 是字符串而非数组，你可以插入任意分隔文字、括号、着色组，这是数组式的 prompt_order 做不到的。

从源码结构看，根配置结构体 StarshipRootConfig 中的 format 字段就是该值的落点，见 src/configs/starship_root.rs。该文件还保留了 PROMPT_ORDER 常量，列出 Starship 内置的默认模块顺序（username、hostname、localip、directory、git_branch、git_commit、git_state、git_status 等）——可以推断这就是旧版 prompt_order 机制所依据的默认渲染序列，升级后你无需显式写出它，只要不覆盖 format 即可保持默认顺序。

模块 prefix / suffix 被模块级 format 取代

在 v0.45.0 之前，部分模块通过 prefix 和/或 suffix 来装饰自身的渲染方式。v0.45.0 改为接受 format 值：不再为上下文字段定义前缀后缀，而是把字段作为变量直接内联进一个代表模块输出的格式串中。

v0.45.0 之前的配置示例

[cmd_duration]
prefix = "took "

v0.45.0 的配置示例

[cmd_duration]
# $duration – The command duration (e.g. "15s")
# $style    – The default style of the module (e.g. "bold yellow")
format = "took $duration "

format 字符串的语法

新 format 语法由一套 PEG 文法定义，见 src/formatter/spec.pest，关键规则如下：

• variable：$变量名（如 $duration）或 ${作用域名} 形式（如 ${env:HOST}），变量名由字母、数字和下划线组成；
• textgroup：format，即方括号内是格式串（可含任意数量的变量、文本或嵌套 textgroup），圆括号内是样式串；
• conditional：(format)，当组内所有变量均为空时整组不渲染；
• escape：[、]、(、)、\、$ 六个功能字符必须用 \ 转义才能作为普通文本出现。

解析入口是 src/formatter/parser.rs 中的 parse() 函数，它基于 pest 解析器把 format 串解析为 Text、Variable、TextGroup、Conditional 四种元素（见 src/formatter/mod.rs 的模块组织），随后由 src/formatter/string_formatter.rs 在运行时做变量替换。这也解释了为什么 git_status 的默认 format 里大量使用 \[、\] 转义。

受影响模块逐一迁移对照

以下小节完整继承官方文档的"被移除属性 → 替代属性"表格与默认配置 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 的默认值即为 format: "$symbol "、success_symbol: "❯"、error_symbol: "❯"（默认错误符号已演进为红色粗体 ❯ 而非 ✖，✖ 风格属于旧行为，可按上面 toml 自行恢复）；src/modules/character.rs 展示了选择逻辑——exit_code == "0" 时取 success_symbol，否则取 error_symbol，并支持 vim 模式的 vicmd_symbol 等符号。同文件中的 failure_status 测试用例验证了退出码 1、54321、-5000 均渲染为红色粗体符号，与迁移文档的"非零即用 error_symbol"语义一致。

Command Duration

被移除属性	替代属性
prefix	format

默认配置变更

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

源码印证：src/configs/cmd_duration.rs 中 CmdDurationConfig 的默认 format 正是 "took $duration "，默认 style 为 "yellow bold"，min_time 为 2_000 毫秒——即命令耗时不足 2 秒时该模块不显示，$duration 变量由模块填充（例如 "15s"）。

Directory

被移除属性	替代属性
prefix	format

默认配置变更

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

新 format 额外引入 $read_only 与 $read_only_style 两个变量，用于在目录只读时追加标记，这是旧的 prefix = "in " 无法表达的。

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\) '

注意方括号用 \[、\] 转义后才成为普通文本；( $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 中 GitStatusConfig 包含 ahead、behind、diverged、up_to_date 等字段，默认值分别为 ⇡、⇣、⇕、空串，format 默认值与上面 diff 完全一致；$ahead_behind 变量即由这三个字段的渲染结果拼接而成。

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) '

Time

被移除属性	替代属性
format	time_format

默认配置变更

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

这是唯一一处属性名互换而非前缀后缀替换的模块：旧 format 里的时间模板语义被独立为 time_format（strftime 风格，如 %T），原属性名让位给新的模块格式串。

Custom Commands

被移除属性	替代属性
prefix	format
suffix	format

默认配置变更

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

迁移清单与验证建议

按以下顺序改写你的 ~/.config/starship.toml：

1. 删除 prompt_order 数组，改写为根级 format 字符串（每行 \ 续行），模块名统一加 $ 前缀；
2. 逐模块检查：凡出现 prefix / suffix 的，改写为带变量的 format（参照上表各模块默认 format）；
3. [character] 的 symbol / use_symbol_for_status / style_success / style_failure 分别迁到 success_symbol / error_symbol，注意新格式串自带尾部空格；
4. [time] 的旧 format（时间模板）改写到 time_format，模块格式串使用新 format；
5. [git_status] 的 show_sync_count = true 迁移为 ahead / behind / diverged 三个属性。

验证方式：改写后对比各模块实际输出与 src/configs/ 下对应文件的默认值（例如 src/configs/character.rs、src/configs/git_status.rs），并留意仓库的 docs/public/config-schema.json 可作为配置字段的机器可读参照。

适用前提与限制：本迁移仅面向从 v0.45.0 之前版本升级的用户；当前仓库代码已在此之后继续演进（例如 character 默认 error_symbol 已由 ✖ 风格演进为红色粗体 ❯，模块列表也新增了若干条目），以当前仓库 src/configs/starship_root.rs 中的 PROMPT_ORDER 为准可确认最新的默认模块顺序。