Starship 高级配置完全指南：瞬态提示符、Shell 钩子函数、右侧提示符与 Claude Code Statusline

Starship 高级配置完全指南：瞬态提示符、Shell 钩子函数、右侧提示符与 Claude Code Statusline

【免费下载链接】starship☄🌌️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship

Starship 是极简、高速且无限可定制的 Shell 提示符框架。当常规的starship.toml配置无法满足需求时，你还可以通过各 Shell 自身的机制实现瞬态提示符（Transient Prompt）、pre-prompt/pre-exec 钩子、终端窗口标题动态化、右侧提示符（Right Prompt）、续行提示符（Continuation Prompt），甚至将 Starship 用作 Claude Code 的实时状态栏（Statusline）。读完本文，你将掌握 PowerShell、Cmd（Clink）、Fish、Bash（Ble.sh）、Zsh 五类 Shell 环境下这些高级特性的完整配置方法，并能用样式字符串（Style Strings）精确定制每一个模块的显示效果。

[!WARNING] 本节涉及的配置在 Starship 未来版本中可能发生变更，升级 Starship 后建议重新核对本文内容。

瞬态提示符（Transient Prompt）：让历史命令区回归简洁

瞬态提示符的核心思想是：当一条命令执行完毕后，把屏幕上已经"用过的"旧提示符替换成一段更精简的内容，从而让终端的历史输出区更干净、更聚焦。它的典型使用场景是：命令输入过程中需要完整信息（Git 分支、运行环境、耗时等），但命令执行结束后这些信息已经不再重要。Starship 在每个 Shell 中通过不同的机制暴露这一能力，下面逐一说明。

PowerShell：Enable-TransientPrompt / Disable-TransientPrompt

在 PowerShell 会话中运行Enable-TransientPrompt即可开启瞬态提示符；将其写入$PROFILE可永久生效。随时可用Disable-TransientPrompt动态关闭。

默认情况下，输入区左侧会被替换为>。若要自定义替换内容，定义名为Invoke-Starship-TransientFunction的函数即可。例如，在旧提示符位置显示 Starship 的character模块：

function Invoke-Starship-TransientFunction { &starship module character } Invoke-Expression (&starship init powershell) Enable-TransientPrompt

从源码看，这套机制的实际实现位于 src/init/starship.ps1：Enable-TransientPrompt通过Set-PSReadLineKeyHandler -Key Enter绑定回车键，在按下回车时先检查命令语法是否合法（$parseErrors.Count -eq 0），只有语法正确才会触发瞬态替换并重新渲染提示符；Disable-TransientPrompt则把回车键恢复为默认的AcceptLine。这意味着语法不完整的命令不会触发瞬态提示符，与文档中 Fish 的行为保持一致。

Cmd：Clink 的 prompt.transient 与 Lua 钩子

在 Windows Cmd 下，瞬态提示符由 Clink 提供。只需执行一次clink set prompt.transient <value>即可配置，<value>取值为：

然后编辑starship.lua自定义左右两侧的替换内容：

• 左侧默认替换为>。定义starship_transient_prompt_func函数即可自定义，该函数会收到当前提示符字符串。例如显示character模块：

function starship_transient_prompt_func(prompt) return io.popen("starship module character" .." --keymap="..rl.getvariable('keymap') ):read("*a") end load(io.popen('starship init cmd'):read("*a"))()

• 右侧默认为空。定义starship_transient_rprompt_func函数即可自定义。例如显示上一条命令开始执行的时间：

function starship_transient_rprompt_func(prompt) return io.popen("starship module time"):read("*a") end load(io.popen('starship init cmd'):read("*a"))()

在 src/init/starship.lua 中可以确认，starship.lua中的promptfilter与rightfilter会检测这两个函数是否存在，存在则用其返回值作为瞬态提示符内容。

Fish：enable_transience / disable_transience

Fish 下运行enable_transience开启瞬态提示符，将其写入~/.config/fish/config.fish可永久生效；disable_transience可随时关闭。

需要特别注意：Fish 只在命令行非空且语法正确时才会打印瞬态提示符。

• 左侧默认替换为加粗绿色的❯。定义starship_transient_prompt_func自定义，例如显示character模块：

function starship_transient_prompt_func starship module character end starship init fish | source enable_transience

• 右侧默认为空。定义starship_transient_rprompt_func自定义，例如显示上一条命令开始执行的时间：

function starship_transient_rprompt_func starship module time end starship init fish | source enable_transience

从 src/init/starship.fish 的实现可以看到一个重要的版本差异：当 Fish 版本 ≥ 4.1 时，enable_transience直接设置全局变量fish_transient_prompt 1使用 Fish 内建的瞬态提示符支持；在更早版本中则通过bind --user \r __starship_transient_execute绑定回车键实现。同时starship_transient_prompt_func/starship_transient_rprompt_func在渲染时会被注入--terminal-width、--status、--keymap、--cmd-duration、--jobs等运行时参数（见 src/init/starship.fish）。

Bash：通过 Ble.sh 实现

Bash 需要依赖 Ble.sh（v0.4 及以上）才能替换已打印的提示符。在~/.bashrc中加入bleopt prompt_ps1_transient=<value>即可开启：

<value>是一个以冒号分隔的列表，可包含always、same-dir、trim三个字段，其语义为：

• 当prompt_ps1_final为空、且prompt_ps1_transient为非空值时，离开当前命令行时PS1指定的提示符会被擦除；
• 若<value>包含trim字段，多行PS1只保留最后一行，其余行被擦除；否则命令行会按PS1=被重绘；
• 若<value>包含same-dir字段，且当前工作目录与上一条命令结束时的目录不同，则prompt_ps1_transient会被忽略（即仅在目录未变化时生效）。

随后编辑~/.blerc（或~/.config/blesh/init.sh）自定义左右两侧：

• 配置prompt_ps1_final自定义左侧替换内容，例如显示character模块：

bleopt prompt_ps1_final='$(starship module character)'

• 配置prompt_rps1_final自定义右侧替换内容，例如显示上一条命令开始执行的时间：

bleopt prompt_rps1_final='$(starship module time)'

自定义 pre-prompt 与 pre-execution 钩子函数

钩子函数让你在"提示符即将绘制"和"命令即将执行"两个时机插入自定义逻辑，例如打印装饰字符、记录命令历史、修改窗口标题等。

Cmd（Clink）：starship_preprompt_user_func / starship_precmd_user_func

Clink 提供了非常灵活的 API，配合 Starship 使用很简单。按需编辑starship.lua：

• 在提示符绘制前执行自定义函数：定义starship_preprompt_user_func，该函数收到当前提示符字符串。例如在提示符前画一个火箭：

function starship_preprompt_user_func(prompt) print("🚀") end load(io.popen('starship init cmd'):read("*a"))()

• 在命令执行前执行自定义函数：定义starship_precmd_user_func，该函数收到将要执行的命令行字符串。例如打印即将执行的命令：

function starship_precmd_user_func(line) print("Executing: "..line) end load(io.popen('starship init cmd'):read("*a"))()

从 src/init/starship.lua 的源码可以看到，starship_precmd_user_func在clink.onendedit事件中被调用（携带当前命令行），starship_preprompt_user_func在promptfilter中被调用（携带待渲染的提示符），这正是 Clink 的"编辑结束"与"提示符过滤"两个生命周期点。

Bash：precmd 变量与 DEBUG trap

Bash 没有其他 Shell 那种正式的 preexec/precmd 框架，因此无法提供完全自定义的钩子，但 Starship 允许你把自己的函数插入提示符渲染流程：

• 在提示符绘制前执行自定义函数：定义函数后，将其名称赋给starship_precmd_user_func。例如：

function blastoff(){ echo "🚀" } starship_precmd_user_func="blastoff"

• 在命令执行前执行自定义函数：使用 Bash 的DEBUGtrap 机制。但必须在初始化 Starship 之前就 trap DEBUG 信号！Starship 会保留 DEBUG trap 的值，但如果在 Starship 启动之后再覆盖 trap，部分功能会损坏。正确写法：

function blastoff(){ echo "🚀" } trap blastoff DEBUG # Trap DEBUG *before* running starship set -o functrace eval $(starship init bash) set +o functrace

src/init/starship.bash 中保留了starship_precmd_user_func的取值逻辑，印证了"预先把函数名交给 Starship"这一约定。

PowerShell：Invoke-Starship-PreCommand

PowerShell 同样没有正式的 preexec/precmd 框架，Starship 通过约定函数名提供有限的插入能力。创建一个名为Invoke-Starship-PreCommand的函数即可：

function Invoke-Starship-PreCommand { $host.ui.Write("🚀") }

修改终端窗口标题

部分 Shell 会自动修改终端窗口标题（例如显示当前目录，Fish 默认就会这么做）。Starship 本身不做这件事，但给bash、zsh、cmd、powershell加上这个功能非常简单。

首先定义一个窗口标题修改函数（bash 与 zsh 通用）：

function set_win_title(){ echo -ne "\033]0; YOUR_WINDOW_TITLE_HERE \007" }

可以使用变量自定义标题，$USER、$HOSTNAME、$PWD是最常用的几个。

• bash：把函数名设为 Starship 的 precmd 函数：

starship_precmd_user_func="set_win_title"

• zsh：把函数加入precmd_functions数组：

precmd_functions+=(set_win_title)

效果满意后，把这些行加入 Shell 配置文件（~/.bashrc或~/.zshrc）即可每次启动新 Shell 时自动生效。例如在终端 tab 标题中显示当前目录名：

function set_win_title(){ echo -ne "\033]0; $(basename "$PWD") \007" } starship_precmd_user_func="set_win_title"

• Cmd：通过starship_preprompt_user_func修改窗口标题：

function starship_preprompt_user_func(prompt) console.settitle(os.getenv('USERNAME').."@"..os.getenv('COMPUTERNAME')..": "..os.getcwd()) end load(io.popen('starship init cmd'):read("*a"))()

• PowerShell：创建名为Invoke-Starship-PreCommand的函数（编辑$PROFILE）：

# edit $PROFILE function Invoke-Starship-PreCommand { $host.ui.RawUI.WindowTitle = "$env:USERNAME@$env:COMPUTERNAME`: $pwd `a" } Invoke-Expression (&starship init powershell)

启用右侧提示符（Right Prompt）：right_format

部分 Shell 支持与输入行同排渲染的右侧提示符。Starship 通过right_format选项设置右侧提示符内容。任何可用于format的模块都能用于right_format；而$all变量只会包含既未在format也未在right_format中显式使用的模块。

注意：右侧提示符是紧跟输入位置的单行。若要在多行提示符中把模块右对齐到输入行上方，请使用 fill 模块。

right_format当前支持以下 Shell：elvish、fish、zsh、xonsh、cmd、nushell、bash。其中 bash 使用右侧提示符需要安装 Ble.sh v0.4 或更高版本。

配置示例

# ~/.config/starship.toml # 极简左侧提示符 format = """$character""" # 把其余模块移到右侧 right_format = """$all"""

渲染效果类似：

▶ starship on  rprompt [!] is 📦 v0.57.0 via 🦀 v1.54.0 took 17s

使用 zsh（v5.0.5+）时，Shell 会给右侧提示符自动添加一个默认尾随空格。当使用 Starship 的$fill模块时这可能导致对齐问题。要消除这个间隙，在.zshrc中加入：

ZLE_RPROMPT_INDENT=0

续行提示符（Continuation Prompt）

部分 Shell 支持与普通提示符配套的续行提示符：当用户输入了不完整的语句（例如单独的左括号或引号）时，会用续行提示符替代普通提示符渲染。

Starship 通过continuation_prompt选项设置续行提示符，默认值为'∙ '。

两个重要约束：

• continuation_prompt必须设置为不含任何变量的字面字符串；
• 续行提示符仅在以下 Shell 中可用：bash、zsh、PowerShell。

配置示例

# ~/.config/starship.toml # 显示两个实心箭头的续行提示符 continuation_prompt = '▶▶ '

Claude Code Statusline：把 Starship 变成 AI 编程的实时状态栏

Starship 支持在 Claude Code（Anthropic 的交互式 AI 编程 CLI 工具）内部渲染自定义状态栏。该状态栏实时展示 Claude 会话信息：当前使用的模型、上下文窗口占用、以及会话成本。

设置方式

要让 Starship 成为 Claude Code 的状态栏，二选一：

1. 在 Claude Code 中运行/statusline并让它配置 Starship；
2. 手动在.claude/settings.json中加入：

{ "statusLine": { "type": "command", "command": "starship statusline claude-code" } }

然后在~/.config/starship.toml中自定义状态栏外观（见下文配置）。

工作原理与数据来源

当以starship statusline claude-code调用时，Starship 通过stdin接收 Claude Code 的会话数据，并使用名为claude-code的专属 profile 渲染状态栏。默认 profile 格式为：

[profiles] claude-code = "$claude_model$git_branch$claude_context$claude_cost"

该 profile 包含三个专用模块：

• claude_model：显示当前使用的 Claude 模型；
• claude_context：以可视化仪表显示上下文窗口占用；
• claude_cost：显示会话成本与统计信息。

从源码看，stdin 会话数据的反序列化结构定义在 src/utils/statusline.rs：ClaudeCodeData包含model（id与display_name）、context_window（context_window_size、total_input_tokens、total_output_tokens、used_percentage、current_usage，其中current_usage细分当次 API 调用的输入/输出/cache 创建/cache 读取 token）、cost（total_cost_usd、total_duration_ms、total_api_duration_ms、total_lines_added、total_lines_removed）以及effort（推理力度级别）等字段，并有配套单元测试验证各类 payload 的反序列化。statusline子命令本身定义在 src/main.rs，支持--profile参数指定渲染所用的 profile。

整体配置入口

你可以通过修改claude-codeprofile 及各个模块的配置来定制状态栏：

# ~/.config/starship.toml # 自定义 claude-code profile [profiles] claude-code = "$claude_model$claude_context$claude_cost" # 配置各模块 [claude_model] format = "$symbol$model " symbol = "🤖 " style = "bold blue" [claude_context] format = "$gauge $percentage " gauge_width = 10 [claude_cost] format = "$symbol$cost " symbol = "💰 "

claude_model 模块

claude_model显示当前会话使用的 Claude 模型。

选项：

变量：

*: 该变量只能用作 style 字符串的一部分。

示例：

# ~/.config/starship.toml # 基础定制 [claude_model] format = "on $symbol$model " symbol = "🧠 " style = "bold cyan" # 为厂商专有模型名设置别名 # 可以按模型 ID 或显示名称设置别名 [claude_model.model_aliases] # 按厂商模型 ID 设置别名（例如 AWS Bedrock） "global.anthropic.claude-sonnet-4-5-20250929-v1:0" = "Sonnet 4.5" # 按显示名称设置别名 "Claude Sonnet 4.5 (Vendor Proxy)" = "Sonnet"

以上默认值可在 src/configs/claude_model.rs 中确认；model_aliases在配置结构中使用IndexMap<String, &str>存储，保证别名顺序稳定。

claude_context 模块

claude_context以百分比和可视化仪表显示上下文窗口占用，样式会根据可配置的阈值自动切换。

选项：

以上默认值（gauge_width: 5、gauge_full_symbol: "█"及默认阈值 0/30/60/80）可在 src/configs/claude_context.rs 中核对。

Display 子配置：display是一个对象数组，定义不同占用级别对应的阈值与样式。模块会采用匹配到的最高阈值对应的样式；若匹配项hidden为true则隐藏模块。

默认的 display 配置：

[[claude_context.display]] threshold = 0 hidden = true [[claude_context.display]] threshold = 30 style = "bold green" [[claude_context.display]] threshold = 60 style = "bold yellow" [[claude_context.display]] threshold = 80 style = "bold red"

变量：

*: 该变量只能用作 style 字符串的一部分。

示例：

仅仪表的最小化显示：

# ~/.config/starship.toml [claude_context] format = "$gauge " gauge_width = 10

详细的 token 信息：

# ~/.config/starship.toml [claude_context] format = "$percentage ($input_tokens in / $output_tokens out) "

自定义仪表符号：

# ~/.config/starship.toml [claude_context] gauge_full_symbol = "▰" gauge_partial_symbol = "" gauge_empty_symbol = "▱" gauge_width = 10 format = "$gauge "

自定义阈值：

# ~/.config/starship.toml [[claude_context.display]] threshold = 0 style = "bold green" [[claude_context.display]] threshold = 50 style = "bold yellow" [[claude_context.display]] threshold = 75 style = "bold orange" [[claude_context.display]] threshold = 90 style = "bold red"

claude_cost 模块

claude_cost以美元显示当前 Claude Code 会话的总成本。与claude_context类似，它也支持基于阈值的样式切换。

选项：

默认值同样在 src/configs/claude_cost.rs 中有对应实现：format: "$symbol(\$$cost) "、symbol: "💰 "、默认 display 阈值 0.0/1.0/5.0。

Display 子配置：display是一个对象数组，定义成本阈值与样式。模块采用匹配到的最高阈值对应的样式；若匹配项hidden为true则隐藏模块。

默认配置：

[[claude_cost.display]] threshold = 0.0 hidden = true [[claude_cost.display]] threshold = 1.0 style = "bold yellow" [[claude_cost.display]] threshold = 5.0 style = "bold red"

变量：

*: 该变量只能用作 style 字符串的一部分。

示例：

# ~/.config/starship.toml # 成本与代码变更统计 [claude_cost] format = "$symbol$cost (+$lines_added -$lines_removed) " # 成本超过 $0.10 前隐藏模块 [[claude_cost.display]] threshold = 0.0 hidden = true [[claude_cost.display]] threshold = 0.10 style = "bold yellow" [[claude_cost.display]] threshold = 2.0 style = "bold red" # 显示时长信息 [claude_cost] format = "$symbol$cost ($duration) "

样式字符串（Style Strings）完全语法

样式字符串是一组用空白分隔的单词，单词不区分大小写（bold与BoLd被视为同一字符串）。每个单词可以是：

• bold
• italic
• underline
• dimmed
• inverted
• blink
• hidden
• strikethrough
• bg:<color>
• fg:<color>
• <color>
• none

其中<color>是颜色说明符（见下文）。fg:<color>与<color>目前行为相同，但未来可能改变。<color>还可以设为prev_fg或prev_bg，分别表示前一个元素的前景色或背景色（若可用），否则为none。inverted会交换背景色与前景色。字符串中单词的顺序无关紧要。

none的语义需要特别注意：

• 只要none不是bg:说明符的一部分，它就会覆盖字符串中所有其他标记。例如fg:red none fg:blue仍然会生成无任何样式的字符串。
• bg:none把背景设为默认色，因此fg:red bg:none等价于red或fg:red；bg:green fg:red bg:none同样等价于fg:red或red。
• 未来版本中，none与其他标记混用可能变成错误用法。

颜色说明符可以是以下三种之一：

• 标准终端颜色之一：black、red、green、blue、yellow、purple、cyan、white。可加上bright-前缀得到高亮版本（例如bright-white）。
• 以#开头的六位十六进制数，表示 RGB 颜色十六进制码（例如#ff0000）。
• 0-255 之间的数字，表示 8-bit ANSI 颜色码。

如果前景/背景同时指定了多个颜色，字符串中最后一个颜色优先。

已知的终端兼容性问题：

• 许多终端默认禁用blink支持；
• iTerm 不支持hidden；
• macOS 默认的 Terminal.app 不支持strikethrough。

因此并非所有样式字符串都能在所有终端正确显示，跨终端使用时建议测试验证。

总结与适用范围

本文覆盖了 Starship 在starship.toml之外的六大高级能力，按 Shell 归纳如下：

所有高级配置均以~/.config/starship.toml为最终落点，相关模块的配置结构定义可继续查阅 src/configs/claude_model.rs、src/configs/claude_context.rs、src/configs/claude_cost.rs 与 src/utils/statusline.rs。由于本节配置在未来版本中可能调整，升级 Starship 后建议回归验证。

【免费下载链接】starship☄🌌️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship