Starship Bracketed Segments 预设：把所有内置模块提示符改写为方括号风格的完整指南

本文讲解 Starship 的 bracketed-segments 预设：它如何将所有内置模块（云环境、语言运行时、Git 状态等）从默认的 "via / on" 英文措辞统一改写为 [符号 值] 的方括号风格。读完本文，你将掌握该预设的一条命令部署方式、完整 TOML 配置中每个模块 format 的含义，以及 Starship format 字符串语法与 starship preset 命令背后的源码机制。

预设做了什么

Starship 的默认提示符中，各模块使用自然语言连接词组织信息，例如 "via v1.7.6.0"、"on main"。bracketed-segments 预设则把所有内置模块的 format 重写为方括号包裹的形式，让每一个信息段都以 [...] 呈现，视觉边界更清晰、信息密度更高。官方文档对该预设的定义（见 docs/bn-BD/presets/bracketed-segments.md，与 英文原版 内容一致）：

This preset changes the format of all the built-in modules to show their segment in brackets instead of using the default Starship wording ("via", "on", etc.).

该预设只改写各模块的 format 字段，不改动任何颜色、字体或显示条件——各模块原有的 $style 配色方案与显示时机全部保持 Starship 默认值，因此切换成本极低、随时可回退。

应用后的实际效果

下面是官方仓库提供的该预设运行截图（zsh 环境）：目录段后面依次是 [ main]（git 分支）、[?]（存在脏状态）、[ v1.1.0]（cargo 包版本）、[ v1.58.1]（Rust 版本）；执行 sudo 后提示符前出现红色的 [root]；命令耗时以 [⏱3s] 收尾。

一条命令部署预设

应用方式与所有 Starship 预设相同，一条命令即可将完整配置写入配置文件：

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

各参数说明：

参数	说明
bracketed-segments	预设名称，starship preset --list 可查看全部可用预设
-o ~/.config/starship.toml	将预设内容写入该文件（即 Starship 的默认配置路径）；省略 -o 时内容输出到 stdout
-f	目标文件已存在时强制覆盖（不传则拒绝覆写已有配置）

写入完成后重新打开终端（或 source 你的 shell 配置）即可看到效果。想换回默认样式时，只需删除或恢复 ~/.config/starship.toml 中对应的 format 行。

预设完整 TOML 配置解析

预设的完整配置为 bracketed-segments.toml（文档通过 VitePress 的 <<< @/public/presets/toml/bracketed-segments.toml 指令将其全文内嵌）。文件首行声明了 JSON Schema 以便编辑器校验：

"$schema" = 'https://starship.rs/config-schema.json'

云服务与环境模块

[aws]
format = '\[[$symbol($profile)(\($region\))(\[$duration\])]($style)\]'

[azure]
format = '\[$symbol($subscription)\]'

[gcloud]
format = '\[$symbol$account(@$domain)(\($region\))\]'

[kubernetes]
format = '\[$symbol$context( \($namespace\))\]'

[openstack]
format = '\[$symbol$cloud(\($project\))\]'

以 aws 为例：$profile、$region、$duration 均被可选组包裹，任何一个缺失时对应部分（连同其内嵌的括号）整体不显示——例如只有 profile 时显示 [ dev-profile]，同时有 region 与 duration 时显示 [ dev-profile(us-west-2)[1m 2s]]。kubernetes 段中 $context 是必填段，$namespace 有值时额外显示为 (default)。

语言运行时模块（节选，完整清单见文末附录）

[c]
format = '\[$symbol($version(-$name))\]'

[cpp]
format = '\[$symbol($version(-$name))\]'

[dotnet]
format = '\[$symbol($version)(🎯 $tfm)\]'

[elixir]
format = '\[$symbol($version \(OTP $otp_version\))\]'

[go]
format = '\[$symbol($version)\]'

[ocaml]
format = '\[$symbol($version)(\($switch_indicator$switch_name\))\]'

[python]
format = '\[$symbol($pyenv_prefix)(${version})(\($virtualenv\))\]'

[rust]
format = '\[$symbol($version)\]'

[nodejs]
format = '\[$symbol($version)\]'

绝大多数运行时模块共享同一模板 $symbol($version)：语言图标加版本号，全部包进方括号并套用该模块默认色。少数模块携带额外信息：c/cpp 在有工具链文件名时追加 (-$name)（如 (-gcc)）；dotnet 有目标框架时追加 🎯 $tfm；elixir 固定显示 OTP 版本；python 支持 pyenv 前缀与虚拟环境名。

版本管理与包管理模块

[conda]
format = '\[$symbol$environment\]'

[direnv]
format = '\[$symbol$loaded/$allowed\]'

[guix_shell]
format = '\[$symbol\]'

[meson]
format = '\[$symbol$project\]'

[mise]
format = '\[$symbol$health\]'

[nix_shell]
format = '\[$symbol$state( \($name\))\]'

[package]
format = '\[$symbol$version\]'

[pixi]
format = '\[$symbol$version( $environment)\]'

[spack]
format = '\[$symbol$environment\]'

conda、nix_shell、spack、package 这类环境指示模块统一为 [符号 环境名] 形式，其中 nix_shell 会区分 pure / impure 状态（$state），有 channel 名时追加 (channel-name)。

Git 系列模块

[fossil_branch]
format = '\[$symbol$branch\]'

[fossil_metrics]
format = '\[$added\][-$deleted\]'

[git_branch]
format = '\[$symbol$branch\]'

[git_commit]
format = '\[(($hash$tag))\]'

[git_metrics]
format = '\[$added\][-$deleted\]'

[git_state]
format = '\[$state ($progress_current/$progress_total)\]'

[git_status]
format = '([\[$all_status$ahead_behind\]]($style))'

[hg_branch]
format = '\[$symbol$branch\]'

[jj_bookmark]
format = '\[$symbol$bookmark(@$remote)$diverged( \(+$overflow_count others\))\]'

注意 git_metrics 与 fossil_metrics 的写法是相邻的两个独立方括号段 [+2][−1]，而不是把增删数塞进同一个括号；git_status 用 '(...)' 可选组合包裹，使"干净状态时整个 Git 状态段消失"的行为与默认一致。

系统状态与其他模块

[battery]
format = '\[$symbol$percentage\]'

[character]  # 该预设未涉及，保持默认

[cmd_duration]
format = '\[⏱ $duration\]'

[jobs]
format = '\[$symbol$number\]'

[localip]
format = '\[$localipv4\]'

[memory_usage]
format = '\$symbol[$ram( | $swap)\]'

[os]
format = '\[$symbol\]'

[shell]
format = '\[$indicator\]'

[status]
format = '\[$symbol$status\]'

[sudo]
format = '\[as $symbol\]'

[time]
format = '\[$time\]'

[username]
format = '\[$user\]'

[root]（截图中红色段）即来自 username 段：show_always 时 $user 直接入括号。

完整模块 format 附录

以下是 bracketed-segments.toml 中全部 89 个模块的完整 format 清单，可整段复制作为配置基准：

[buf]
format = '\[$symbol($version)\]'

[bun]
format = '\[$symbol($version)\]'

[cmake]
format = '\[$symbol($version)\]'

[cobol]
format = '\[$symbol($version)\]'

[container]
format = '\[[$symbol \[$name\]]($style)\]'

[crystal]
format = '\[$symbol($version)\]'

[daml]
format = '\[$symbol($version)\]'

[dart]
format = '\[$symbol($version)\]'

[deno]
format = '\[$symbol($version)\]'

[docker_context]
format = '\[$symbol$context\]'

[elm]
format = '\[$symbol($version)\]'

[erlang]
format = '\[$symbol($version)\]'

[fennel]
format = '\[$symbol($version)\]'

[fortran]
format = '\[$symbol($version)\]'

[gleam]
format = '\[$symbol($version)\]'

[gradle]
format = '\[$symbol($version)\]'

[haskell]
format = '\[$symbol($version)\]'

[haxe]
format = '\[$symbol($version)\]'

[helm]
format = '\[$symbol($version)\]'

[java]
format = '\[$symbol($version)\]'

[jobs]
format = '\[$symbol$number\]'

[julia]
format = '\[$symbol($version)\]'

[kotlin]
format = '\[$symbol($version)\]'

[lua]
format = '\[$symbol($version)\]'

[maven]
format = '\[$symbol($version)\]'

[mojo]
format = '\[$symbol($version)\]'

[nats]
format = '\[$symbol$name\]'

[netns]
format = '\[[$symbol \[$name\]]($style)\]'

[nim]
format = '\[$symbol($version)\]'

[opa]
format = '\[$symbol($version)\]'

[perl]
format = '\[$symbol($version)\]'

[php]
format = '\[$symbol($version)\]'

[pijul_channel]
format = '\[$symbol$channel\]'

[pulumi]
format = '\[$symbol$stack\]'

[purescript]
format = '\[$symbol($version)\]'

[quarto]
format = '\[$symbol($version)\]'

[raku]
format = '\[$symbol($version-$vm_version)\]'

[red]
format = '\[$symbol($version)\]'

[rlang]
format = '\[$symbol($version)\]'

[ruby]
format = '\[$symbol($version)\]'

[scala]
format = '\[$symbol($version)\]'

[singularity]
format = '\[[$symbol\[$env\]]($style)\]'

[solidity]
format = '\[$symbol($version)\]'

[swift]
format = '\[$symbol($version)\]'

[terraform]
format = '\[$symbol$workspace\]'

[typst]
format = '\[$symbol($version)\]'

[vagrant]
format = '\[$symbol($version)\]'

[vcsh]
format = '\vcsh [$symbol$repo\]'

[vlang]
format = '\[$symbol($version)\]'

[xmake]
format = '\[$symbol($version)\]'

[zig]
format = '\[$symbol($version)\]'

（上文"云服务/运行时/Git/系统"各节已覆盖其余全部模块，两者合起来即原文件的全部内容；各模块在 TOML 中的相对顺序与官方文件一致。）

读懂这些 format：Starship 格式语法的三个要点

预设之所以只需覆盖 format 就能改变全部外观，是因为 Starship 提示符完全由 format 字符串驱动。理解以下规则后，你可以逐行读懂上文的配置，也能自行微调：

1. \[ 与 \] 是转义的字面方括号。在 format 中写 \[...\]，渲染结果就是一个可见的 [...]；而未转义的 (...) 是"可选组"语法——组内所有变量都为空（None）时，整组连同其内容一起不显示。docs/config/README.md 对 format 语法的原文说明："When $combined is a shortcut for \[$a$b\], '($combined)' will show nothing only if $a and $b are both None. This works the same as '(\[$a$b\] )'"。这解释了为什么 aws 段中 (\($region\)) 里的括号既做了转义又外包了一层可选组：region 缺失时连字面括号也不显示。

2. $variable 占位符由对应模块填充，如 $version、$branch、$symbol、$style。($symbol) 这种写法意味着该模块的图标本身也是可选的——若你把某模块的 symbol 设为空字符串，方括号内会直接以值开头。

3. ($style) 把整段套用该模块的默认颜色。预设刻意保留这一写法，因此方括号风格不改变 Starship 原有的配色体系；想统一配色时，可把 ($style) 换成自定义样式（如 bold red）或引用 config-schema.json 校验后的样式变量。

底层机制：preset 命令如何工作

从源码看，starship preset 是 Starship 的内置子命令，定义于 src/main.rs（命令参数 name/-o/-f/--list），实际逻辑在 src/print.rs 的 preset_command：

• 预设名称是编译期内置的：Preset 枚举通过 shadow-rs 构建时从仓库的预设文件生成变体列表（shadow::get_preset_list()），运行时用 shadow::get_preset_content(name) 取出对应 TOML 全文——shadow-rs 在 Cargo.toml 中作为构建依赖声明；
• 指定 -o 时调用 write_file_atomic 原子写入目标文件，保证不会写出半截配置；文件已存在且未加 -f 时会报错退出；
• 未指定 -o 时内容直接打印到 stdout，方便 starship preset bracketed-segments > my-config.toml 这类管道用法；
• --list 打印所有可用预设名，等价于 Preset::value_variants() 的展开。

这也解释了文档中"点击下载 TOML"与命令行两条获取途径的一致性：docs/public/presets/toml/bracketed-segments.toml 与二进制内嵌内容同源。

进阶用法与边界

• 选择性套用：不必全盘接受。把 TOML 落到配置文件后，只保留你需要的 [git_branch]、[python] 等段落，其余模块仍走默认措辞，可形成混合风格。
• 与其他预设的关系：bracketed-segments 只改 format、不动图标，因此可与 no-nerd-font 等图标类预设自由组合；而 jetpack、pure-preset 之类是整套覆盖，二者同时使用会互相覆盖 format，以配置文件中出现顺序靠后的模块段为准（同一模块只读一个 [module] 段）。
• 适用前提：预设中的模块名与变量名以当前仓库版本为准（如 [jj_bookmark]、[mise] 是较新加入的模块）；若你的 Starship 版本较旧，个别段落会因模块不存在而被忽略，不影响整体加载。
• 回退方式：恢复默认提示符只需删除 ~/.config/starship.toml（或移除其中对应模块段），无需重新安装。

小结

bracketed-segments 是 Starship 官方预设中改造面最广、侵入性最低的一个：通过 docs/presets/bracketed-segments.md 对应的 bracketed-segments.toml 覆盖 89 个模块的 format，借助 \[...\] 字面括号与 (...) 可选组两种语法，把默认英文措辞统一替换为 [符号 值] 的方括号段。掌握了 format 语法与 starship preset 的内置机制后，你既能一键切换该风格，也能按模块粒度裁剪出自己的提示符形态。