Starship v0.45.0 迁移指南：从 `prompt_order` 到 `format` 的全新配置体系

Starship v0.45.0 是为 v1.0.0 做准备的一次包含破坏性变更（breaking changes）的版本，其核心变化在于：把原先只能“按固定顺序罗列模块”的 prompt_order，以及散落在各模块上的 prefix/suffix/label 等显示属性，统一收编为以根级 format 和模块级 format 为核心的全新配置范式。本指南依据仓库中法文迁移文档 docs/fr-FR/migrating-to-0.45.0/README.md（与 英文原文 完全对应）编写，并结合当前仓库源码（src/configs/*.rs、src/modules/*.rs）逐项印证这些变更的底层实现，帮助你在升级后精确改写 ~/.config/starship.toml，实现比旧版本更强的定制能力。

适用前提：本文面向从 v0.45.0 之前版本升级上来的用户。迁移完成后，建议继续阅读 配置总览 与 进阶配置指南 以掌握新格式字符串的全部语法。

核心变更总览：为什么需要一次“迁移”

在 v0.45.0 之前，Starship 的定制体系存在两个明显的局限：

1. 模块顺序只能通过数组指定：prompt_order 接收一组模块名（如 "username"、"directory"、"git_branch"），Starship 按数组顺序渲染模块，但你无法在模块之间插入任意文本、符号或自定义样式。
2. 模块外观靠“打补丁”：各模块通过 prefix/suffix（有些模块还有 symbol、label、format）在内容前后硬编码装饰文本，组合起来既零散又难以表达“某些变量在某种状态下才显示”这类逻辑。

v0.45.0 的破坏性变更（非向后兼容）正是为了支持“在模块之外进行定制”以及“在模块内部自由编排变量”，从而为 v1.0.0 的稳定配置体系铺路。新版把定制能力统一抽象为 format 字符串：它由普通文本、$变量 与 文本组 构成。从当前源码看，src/formatter/ 目录下的 string_formatter.rs 与语法定义文件 spec.pest 就是这套解析器的实现，模块渲染前都会先经过它处理（例如 src/modules/git_status.rs 中 StringFormatter::new(config.format)）。

根级 format 取代 prompt_order

旧版中，你用一个模块名数组声明渲染顺序：

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 字符串。模块名被写成 $模块名 形式的变量，你可以在它们之间随意插入固定文本、换行、空格乃至 [带样式的文本组]：

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

该示例在字符串两端使用了 """ 多行字符串与行尾反斜杠 \ 续行，以保证输出不产生多余换行与缩进。

新体系带来的额外能力

根级 format 不只是“换了个写法”，它让提示符可以被当作一整段可排版文本：

• 模块间自由插入文本：例如在 $directory 后直接写 " ➜ "，无需依赖某个模块的 prefix。
• 加入普通变量与样式组：format 字符串支持普通文本、$变量 和 []() 文本组组合。关于格式字符串的完整语法（变量、文本组、样式字符串、条件格式），参见 配置文档 Format Strings 一节。
• 条件隐藏：以 ( ) 包裹的条件格式字符串，当其中所有变量为空时整段不渲染——这一机制是旧版 prefix/suffix 完全无法实现的（详见 docs/config/README.md）。

模块级 prefix/suffix 被 format 取代

v0.45.0 之前，部分模块接受 prefix 与/或 suffix 来装饰模块的呈现方式。新版本改为接受一个 format 值，将原本“由 prefix/suffix 包裹上下文变量”的方式，变为“在代表模块输出的 format 字符串中自由替换变量”。

以命令耗时模块为例，旧配置为：

[cmd_duration]
prefix = "took "

新配置则直接把 took 与变量、样式写进 format：

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

在这条新配置里：$duration 是上下文变量，会在渲染时被替换成实际耗时；$style 引用模块的默认样式；[ ] 中的内容会套用 ( ) 中给出的样式。实现层面，CmdDurationConfig 的默认值正是 format: "took $duration "，且 style 默认 "yellow bold"、仅在命令超过 min_time（默认 2000ms）时输出（见 src/configs/cmd_duration.rs）。注意对比：旧版只能在模块前加“took ”，新版还能把不同部分染成不同颜色、甚至做嵌套，自由度完全不同。

受影响的模块逐一对照

以下列出 v0.45.0 中所有受影响的模块、被删除的属性及其替代方案，并给出默认配置的 diff 与源码佐证。迁移时，请对照这张清单检查自己的 starship.toml。

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 被合并为一个行为。这一点在当前源码中得到印证：CharacterConfig 只保留 success_symbol、error_symbol 与 vim 相关符号，不再有 use_symbol_for_status 字段，且默认 error_symbol: "❯"（见 src/configs/character.rs）。另外，源码中 vim 命令态字段的字段名是 vimcmd_symbol，同时通过 #[serde(alias = "vicmd_symbol")] 保留了旧名称兼容（同一文件 L14-L15）。

如果你希望保持旧版 use_symbol_for_status = true 的行为——即失败时显示 ✖，请在配置中加入：

[character]
error_symbol = "✖"

注：character 模块默认会在输出后自动追加一个空格（其默认 format 为 "$symbol "，见 src/configs/character.rs），因此与其他模块的 format 示例不同，上面的示例刻意没有在样式组后面补空格。

Command Duration（命令耗时）

被删除的属性	替代方案
prefix	format

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

新版 format 中同时出现了 $duration（实际耗时，如 "15s"）与 $style（默认样式），由此可以把“took”与耗时整体作为一个可换样式的文本组。默认值见 src/configs/cmd_duration.rs。

Directory（目录）

被删除的属性	替代方案
prefix	format

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

新版把路径与只读标记分成两个文本组分别着色。从源码看，DirectoryConfig 默认 format 即为此值，且还新增了面向仓库根目录的 repo_root_format: "$before_root_path$repo_root$path$read_only "，read_only 默认为 "🔒"、read_only_style 默认为 "red"（见 src/configs/directory.rs）——这些都是旧版单个 prefix 表达不了的多段式排版。

Environment Variable（环境变量）

被删除的属性	替代方案
prefix	format
suffix	format

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

env_var 原本用一对空字符串作为前后缀，现在则通过 format 把可选图标 $symbol 与变量值 $env_value 放进同一个带样式文本组（默认值见 src/configs/env_var.rs）。

Git Commit（Git 提交）

被删除的属性	替代方案
prefix	format
suffix	format

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

旧版用前缀 ( 与后缀 ) 手工给哈希加括号，新格式字符串则需要把这两个括号字符转义为 \( 与 \)（因为 ( 与 ) 在 format 字符串中是样式组的语法符号），再放进一个整体着色的文本组。

Git Status（Git 状态）

被删除的属性	替代方案
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 都为空时整段不渲染），内部用转义的 \[ 与 \] 保留方括号，$all_status 展开为各类文件状态符号（modified !、staged +、untracked ? 等），$ahead_behind 展开为与远端的分叉/领先/落后信息。源码 src/configs/git_status.rs 中不仅可以看到这一默认 format，还能看到新版为分支同步信息提供的独立属性：ahead: "⇡"、behind: "⇣"、diverged: "⇕"。

旧版 show_sync_count 的作用是控制是否显示“本地分支领先/落后远端分支的提交数”。v0.45.0 中它被拆成三个独立属性：

• ahead：本地领先远端若干提交时的显示模板；
• behind：本地落后远端若干提交时的显示模板；
• diverged：双方都已分叉（各有新提交）时的显示模板。

如果你希望保留旧版 show_sync_count = true 的行为，请加入以下配置：

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

这三个模板用到了占位变量：领先/落后场景中的 $count 在渲染时被替换为提交数；分叉场景中分别用 $ahead_count、$behind_count 展示两侧数量。模块实现中确实按此语义处理：当同时存在领先与落后时读取 diverged 模板并填充 ahead_count/behind_count，否则按 ahead/behind 分支用 format_count 填充 count（见 src/modules/git_status.rs），测试用例中也验证了 diverged=r"⇕⇡$ahead_count⇣$behind_count" 这类模板的组合输出（src/modules/git_status.rs）。

Hostname（主机名）

被删除的属性	替代方案
prefix	format
suffix	format

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

旧版依赖空前后缀来“消音”，新版本则显式写出 $hostname 变量，并把 in 这样的装饰文本直接并入 format，含义更清晰、也便于整体调整。

Singularity

被删除的属性	替代方案
label	format
prefix	format
suffix	format

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

Singularity 模块原本有独立的 label 属性，如今一并并入 format：容器名 $env 用 \[ 与 \] 转义包裹在方括号中，作为 $symbol 之后的一个可着色文本组（默认 format 见 src/configs/singularity.rs）。

Time（时间）

被删除的属性	替代方案
format	time_format

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

time 模块的新旧 format 含义截然不同，是本次迁移中最容易混淆的一点：

• 旧 format 直接承载了时间显示格式（如 %T），它是 strftime 风格的日期格式串；
• v0.45.0 把这一职责移交给新属性 time_format（仍为 strftime 风格，%T 表示 HH:MM:SS），而 format 变成了与其他模块一致的“输出布局”，其中 $time 变量会被替换为按 time_format 格式化后的时间。

Custom Commands（自定义命令）

被删除的属性	替代方案
prefix	format
suffix	format

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

自定义命令同样受益于新范式：图标 $symbol 与命令输出 $output 被合并进同一个带样式文本组，若要为输出单独染色，直接在 format 中再拆出一个文本组即可，比旧版的空前后缀方案灵活得多。

迁移实操建议与自检清单

完成全部改写后，可以按下面的步骤自查：

1. 搜索残留的旧属性：在 starship.toml 中检索 prompt_order、prefix、suffix、symbol、label、show_sync_count、use_symbol_for_status 等关键词，逐一确认是否属于上述被删除列表；注意 character 模块中“符号”类配置（如 symbol、style_success、style_failure）要改写为 success_symbol/error_symbol，而 time 模块中的 format 要改名为 time_format。
2. 重载并目测输出：修改后重新加载 Starship（不同 shell 的初始化脚本见仓库 src/init/），模拟一次成功命令与一次失败命令（exit 1），确认 character 正确切换成功/失败符号、git_status 在干净与脏工作区下均表现正常。
3. 善用转义：format 字符串中 $ [ ] ( ) 是语法字符，若要显示原字符必须转义。迁移中你大概率会用到 \( \)（git_commit）与 \[ \]（git_status、singularity）等写法，这是新语法带来的必要代价；完整转义规则见 docs/config/README.md。
4. 给编辑器配置补全：基于仓库中的 config-schema.json，可以在支持的编辑器中获得配置项的自动补全与合法性校验（配置文件的写法示例见 docs/config/README.md），有助于在迁移时及时发现拼写错误的属性名。

总结

v0.45.0 这次破坏性变更的收益是结构性的：旧版用 prompt_order（模块排序）+ prefix/suffix（模块装饰）两套彼此割裂的机制控制提示符外观；新版则收敛为“根级 format + 模块级 format”一个统一范式。迁移之后，你可以在模块之间自由插入文本与样式组、在模块内部按变量拼接并条件化渲染任意片段，而这些能力的基础——StringFormatter 及其语法——也正是后续版本继续扩展配置体系的地基。建议在完成迁移后通读 配置总览 中的 Format Strings / Conditional Format Strings 章节与 进阶配置指南，把本次“被迫学习”的新语法变成日后深度定制提示符的常规武器。