Starship v0.45.0 迁移指南：从 prompt_order 与 prefix/suffix 全面转向 format 配置体系

Starship 的 v0.45.0 是一次为大型 v1.0.0 铺路的里程碑式发布，它重构了提示符（prompt）的配置模型：用统一的、可表达样式与布局的 format 模板取代了原先只接受模块名的 prompt_order，以及各模块分散的 prefix/suffix 装饰属性。本文以 docs/id-ID/migrating-to-0.45.0/README.md（迁移文档的印尼语版本，与 docs/migrating-to-0.45.0/README.md 英文原版同源）为主体，逐一拆解每一项破坏性变更的动机、新旧写法对照与迁移后的等价配置，并结合当前仓库源码（仓库 Cargo.toml 所示版本为 1.26.0，上述机制已完全生效）验证其落地形态。读完本文，你将能把手头的旧式 prompt_order 与 prefix/suffix 配置无损迁移为纯 format 写法，并理解为何 format 是 Starship 此后所有可定制性的根基。

迁移背景：v0.45.0 为什么值得"折腾"

v0.45.0 之前，Starship 提示符的渲染顺序完全由顶层数组 prompt_order 决定，它只接受一串模块名，例如 ["username", "hostname", "directory", ...]。这套模型有两个天然局限：

• 只能排列模块，无法表达模块之间的布局——例如想在某个模块前后插入空格、文本或条件分隔符，都必须借助各模块自带的 prefix/suffix 属性拼接，能力被锁死在固定几个属性里；
• 每个模块的装饰配置各自为政——prefix、suffix、甚至内容变量拼进了一个属性各自承载的小格局里，模块越多，风格差异越难统一。

v0.45.0 的决定是把"整条提示符怎么渲染"和"每个模块怎么渲染"都统一交给 format 字符串：模块名变成字符串中的变量（如 $directory），变量可以被包裹进任意静态文本、颜色与风格标记中，从而把原来靠模块排列 + 前后缀拼接才能实现的布局，收敛为一种内聚、可读、可精确控制的描述语言。

顶层变更一：prompt_order → 根级 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",
]

迁移后，在配置文件顶层使用 format 字符串，把上面的每个模块名改写为 $模块名 变量形式，并可任意穿插空格、文本、颜色与样式指令：

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

注意几个写法细节，它们在 v0.45.0 之后一直是官方推荐范式：

• 使用 """\ 开头的多行 TOML 字符串，配合每行末尾的 \（行延续）来去掉换行符，从而在不破坏可读性的前提下生成"逻辑上单行"的模板；
• 末行前的缩进同样依赖 \ 续行符消除，否则缩进空格会被渲染进提示符；
• 变量间想要空格，就在 \$username\ 行与下一行之间显式补一个空格字符（例如文档中 directory 与 git_branch 之间的留白即来自模板自身）。

format 的能力边界远不止"按序渲染模块"：由于整条提示符都是模板，任何模块都可以被静态文本包围、被 样式 标记染色，甚至可以通过条件判断（如 $env_var 是否存在）来决定片段显隐。这一设计使"无限可定制"从口号变成了配置层面的真实能力。更完整的变量与语法说明可参见 docs/config/README.md。

顶层变更二：模块 prefix/suffix → 模块级 format

v0.45.0 之前，若干模块支持 prefix 和/或 suffix 属性，用来渲染该模块前后的装饰内容。这些属性被统一替换为模块自身的 format。原先需要拆成"前缀 + 内容 + 后缀"三段式描述的样式，现在把上下文相关的变量直接代入一条格式字符串，由 format 代表该模块的完整输出。

以 cmd_duration 为例。迁移前的写法是在模块外指定前缀文本：

[cmd_duration]
prefix = "took "

迁移后的等价写法把前缀文本与变量合并进模块的 format，并顺手给耗时上色：

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

其语义为：先输出字面量 took ，然后以 $style 引用的模块默认样式渲染 $duration 变量，末尾保留一个空格作为与下一个模块的间距。这种"字面量 + 变量 + 尾部空格"的组合贯穿了几乎所有迁移后的默认配置，是读懂 Starship 默认行为的一把钥匙。

需要特别强调的是，format 迁移不是一次文本替换就完成的表面工程：渲染器需要真正解析这些模板。在 starship 源码中，模块最终的输出统一交由格式化引擎处理，旧有的 prefix/suffix 概念在当前代码库里已无对应结构（在 src/module.rs 中检索不到任何 prefix/suffix 字段），而各模块的配置结构均以 format: &'a str 作为首要字段，例如 src/configs/cmd_duration.rs 中 CmdDurationConfig 的默认值即为 format: "took $duration "。这从源码层面印证了迁移的彻底性。

受影响的模块逐项拆解

迁移文档用"属性替换对照表 + 默认配置 diff + 特殊行为说明"三种形式，逐模块交代了全部变更。下面逐项继承并补充使用要点。

Character（提示符符号）

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 行为的去向

旧版本里，use_symbol_for_status = true 的作用是：当上一条命令以非零退出码结束时，让提示符显示 error_symbol 而非 symbol。v0.45.0 将这一开关与 error_symbol 合并——现在只要命令以非零状态码结束，就会始终使用 error_symbol，不再需要单独的布尔开关。

若希望行为与旧式 use_symbol_for_status = true 配置保持一致，迁移后只需显式给出一个与成功符号不同的错误符号：

[character]
error_symbol = "✖"

关于尾部空格的注意事项

迁移文档特别提醒：character 模块会自动在符号后面补一个空格。因此与其他模块 format 字符串不同，character 的 success_symbol、error_symbol、vicmd_symbol 等符号值不需要（也不应该）手动在末尾添加空格——这正是上例中符号值后没有空格、而前面其他模块默认 format 尾部却普遍带一个空格的原因。

从源码看，这一约定至今仍然成立：在 src/configs/character.rs 中，CharacterConfig 的默认值为 format: "$symbol "（模块渲染时在符号后补空格），而 success_symbol、error_symbol、vimcmd_symbol 的默认值分别是 ❯、❯、❮，与迁移文档描述的 v0.45.0 默认值完全一致；symbol、use_symbol_for_status 等旧字段在结构体定义中已不存在，vicmd_symbol 则以别名形式保留为 vimcmd_symbol（见 src/configs/character.rs 中 #[serde(alias = "vicmd_symbol")] 的兼容声明）。

Cmd Duration（命令耗时）

被替换的属性	替换后的属性
prefix	format

默认配置变化：

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

迁移前 prefix = "took " 只负责产出纯文本前缀；迁移后 format 用 $duration 把耗时数值按模块样式渲染出来，took 字样从"前缀属性"变成了"格式串字面量"。当前源码中该模块默认 format 与此完全一致（见 src/configs/cmd_duration.rs），同时 CmdDurationConfig 还保留了 min_time、style: "yellow bold"、show_milliseconds 等与格式相互独立的控制项。

Directory（目录）

被替换的属性	替换后的属性
prefix	format

默认配置变化：

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

迁移后不仅前缀 in 并入 format，read_only（只读目录标记，当前默认符号为 🔒，见 src/configs/directory.rs）及其独立样式 read_only_style 也被纳入同一模板，格式串由此可以精确表达"路径 + 锁标 + 各自颜色"的组合输出。这在旧版中仅靠一个 prefix 是无法做到的。

Env Var（环境变量）

被替换的属性	替换后的属性
prefix	format
suffix	format

默认配置变化：

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

env_var 的默认前后缀原本都是空字符串，迁移后统一进 format，输出形如 with <变量值> 的完整模板。由于 format 可以引用变量是否存在来做条件渲染，环境变量模块"仅在目标变量存在时显示"的能力也一并由格式模板接管，而不是依赖外部 disabled 逻辑或前后缀的字符串拼接。

Git Commit（Git 提交哈希）

被替换的属性	替换后的属性
prefix	format
suffix	format

默认配置变化：

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

这是"括号包裹内容"型结构的典型迁移案例：旧写法用 prefix = "("、suffix = ")" 实现包裹；新写法把这些括号作为字面量并入 format。注意格式字符串里的 (、) 属于语法保留字符（用于 变量 结构），因此括号字面量必须转义为 \(、\)。整条 '\($hash\) ' 的含义是：先输出 (，再以模块默认样式渲染 $hash，紧接着输出 )，最后补一个模块间距空格。

Git Status（Git 状态）

git_status 涉及三类属性替换，是迁移复杂度最高的模块：

被替换的属性	替换后的属性
prefix	format
suffix	format
show_sync_count	format

默认配置变化：

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

新的默认 format 逐段解读为：左括号字面量 ( → 转义的中括号对 [ ]（以 \[、\] 写入）→ 在括号内依次渲染 $all_status（工作区状态汇总）与 $ahead_behind（领先/落后信息）→ 以 $style 上色 → 尾部空格。

show_sync_count 拆分为三个符号属性

旧版中，show_sync_count 控制提示符是否显示当前分支相对上游分支"领先/落后多少提交"；v0.45.0 将其替换为三个独立的符号属性 ahead、behind、diverged。若想复刻旧的 show_sync_count = true 行为，迁移后在 git_status 中加入：

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

三个属性分工明确：ahead 在分支领先时显示（⇡ 加提交数 $count）；behind 在分支落后时显示（⇣ 加提交数）；diverged 在分支同时领先又落后（分叉）时显示，同时使用 $ahead_count 与 $behind_count 两个变量分别输出两侧提交数。当前源码中 src/configs/git_status.rs 的 GitStatusConfig 正是以 ahead: "⇡"、behind: "⇣"、diverged: "⇕" 作为独立的可配置默认符号，并在默认 format 中通过 $all_status$ahead_behind 将其统一编排——证明了"数量显示"从单一布尔开关进化成了可自由放入模板的组合符号体系。

Hostname（主机名）

被替换的属性	替换后的属性
prefix	format
suffix	format

默认配置变化：

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

旧版 hostname 的前后缀默认为空，显示的主机名光秃秃地暴露在提示符里；迁移后的默认格式串渲染出带默认样式的主机名与 in 后缀，使主机名模块与后续路径之间自然衔接成类似 <主机名> in <路径> 的语义片段。

Singularity（Singularity 容器）

被替换的属性	替换后的属性
label	format
prefix	format
suffix	format

默认配置变化：

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

旧版的 label 属性被并入 format，[$symbol\[$env\]]($style) 呈现为"符号 + 中括号包裹的环境名"整体上色。\[、\] 同样是对方括号字面量的转义。

Time（时间）

time 模块是少数发生属性语义迁移的案例——旧 format 承担了"时间格式"的职责，与新引入的模块级 format 语义冲突，因此改名：

被替换的属性	替换后的属性
format	time_format

默认配置变化：

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

旧写法里，format = "🕙[ %T ]" 中的 %T 是 strftime 时间格式，且与模块级布局（时钟图标、括号、空格）混在同一个值里；迁移后时间格式与模板分离：time_format = "%T" 专职指定 24 小时制时间 HH:MM:SS 的编码方式，模块级 format = "at 🕙$time " 则控制布局与样式，$time 变量引用经 time_format 格式化后的时间文本。理解这一拆分，就不会在新版本里把时间编码写进模块级 format 而得不到预期结果。

Custom Commands（自定义命令）

被替换的属性	替换后的属性
prefix	format
suffix	format

默认配置变化：

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

custom 模块的默认 format 把自定义命令的符号（$symbol）与命令输出（$output）作为一个整体上色。对高度依赖自由样式的自定义命令来说，模块级 format 的引入尤其重要——开发者可以把 $symbol、$output 分别放入不同样式片段甚至拆到不同位置，形成旧版前后缀无法表达的布局。

从源码视角确认迁移的最终形态

当前仓库处于 v0.45.0 之后的成熟版本（Cargo.toml 中版本为 1.26.0），以下几点可以从源码直接验证 v0.45.0 迁移后的架构不仅落地、而且延续至今：

1. 旧字段在配置结构中彻底消失。以 src/configs/character.rs 为例，CharacterConfig 只包含 format、success_symbol、error_symbol、vimcmd_symbol（及若干 vim 模式符号）等字段，不存在 symbol、style_success、style_failure、use_symbol_for_status 之类的旧属性。git_status、directory、cmd_duration 等模块结构同理（见 src/configs/git_status.rs、src/configs/directory.rs）。

2. 模块渲染逻辑统一走 format。迁移文档所述默认值（如 cmd_duration 的 took $duration 、character 的 format: "$symbol "）均可在对应模块的 Default 实现中原样找到，说明"默认行为即来自默认 format 模板"已成为通用模式，而非个例兼容。

3. prefix/suffix 机制整体退出。在渲染核心 src/module.rs 中已检索不到 prefix/suffix 相关结构，印证模块装饰能力全部收敛到 format 模板的渲染管线中。

4. vicmd_symbol 以 serde 别名保留（#[serde(alias = "vicmd_symbol")]），属于对旧写法的解析兼容，而非运行时行为上的双轨制。

因此，任何运行在当前版本上的用户都不再需要（也无法）使用 prompt_order 或 prefix/suffix；若旧配置中仍残留这些键，它们不会被解析为有效行为。

迁移自查清单

综合上文，将旧配置迁移到 v0.45.0+ 体系时，建议按如下清单逐项核对：

1. 把顶层 prompt_order 数组改写为根级 format 字符串，模块名全部转为 $模块名 变量，并用 \ 续行保持多行可读性；
2. 检查是否存在对 character 的 symbol、style_success、style_failure、use_symbol_for_status 的定制：将成功/失败样式并入 success_symbol 与 error_symbol 的 符号 写法，需要区分错误态时给出不同于成功态的 error_symbol；
3. 全局搜索 prefix、suffix 键，将其字面量与上下文变量合并进各模块 format（directory、env_var、git_commit、git_status、hostname、singularity、custom 等均受影响）；
4. 将 time 模块旧 format 中的 strftime 编码移到新的 time_format，布局留作模块级 format；
5. 若用到 git_status 的 show_sync_count，改用 ahead/behind/diverged 三个符号属性并显式给出带 ${count}、${ahead_count}、${behind_count} 的模板；
6. 记住 character 模块会自动追加空格，其符号值不要再自行补空格；而其他模块的 format 若要维持模块间距，需在模板尾部保留空格；
7. 涉及 (、)、[、] 字面量时，在格式串中转义为 \( \) \[ \]。

完成以上步骤后，配置即进入统一的 format 表达体系。这套体系也是后续版本持续演进、甚至扩展出预设（preset）生态的基础——当前 docs/presets/README.md 下整理的各类预设，其本质都是围绕根级与模块级 format 构建的可复用配置组合。

迁移过程中如遇到某个键不再生效，可随时对照各模块对应的源码配置文件（src/configs 目录下按模块名一一对应）与官方生成的 public/config-schema.json JSON Schema 校验键名合法性，避免把旧属性名残留当成新格式失效。