Starship 高级配置完全指南瞬态提示符、右侧提示、Claude Code 状态栏与样式系统【免费下载链接】starship☄️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship本篇技术指南围绕 Starship 的advanced-config文档展开讲解如何在常规starship.toml配置之外通过各 Shell 的初始化脚本、钩子函数与特殊配置项实现更深度的定制包括 PowerShell / Cmd / Fish / Bash 中的瞬态提示符Transient Prompt、命令执行前后钩子、窗口标题联动、右侧提示right_format、续行提示continuation_prompt、面向 Claude Code 的状态栏Statusline以及贯穿所有模块的样式字符串Style String语法。读完本文你将掌握每项高级特性的启用方式、自定义函数命名约定以及底层初始化脚本中的真实实现细节能够直接复制配置并落地到自己的终端环境。[!WARNING] 本节中的配置在未来版本中可能发生变化升级 Starship 后建议重新核对本文档对应仓库内 docs/advanced-config/README.md 的英文原版。一、瞬态提示符Transient Prompt让历史输出让位于输入瞬态提示符的思想是命令执行完毕、新输入开始前用一段更精简的字符串替换上一行已经打印过的完整提示符。当提示符携带了大量信息git 分支、环境版本、耗时等而并非每条命令都需要这些信息时这一机制能让终端保持清爽。不同 Shell 的启用方式与自定义入口各不相同下面按 Shell 逐一说明。1. PowerShellEnable-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/Disable-TransientPrompt函数提供启用时会为 Enter 键注册PSReadLineKeyHandler在下一次绘制提示符前把$script:TransientPrompt置为true并在提示符函数global:prompt中优先调用Invoke-Starship-TransientFunction若未定义该函数则回退输出默认的粗体绿色❯源码中即$([char]0x1B)[1;32m❯$([char]0x1B)[0m 。注意该实现只解析无语法错误的输入行$parseErrors.Count -eq 0并会临时切换Console.OutputEncoding为 UTF-8 以保证 emoji 图标正确渲染。2. CmdClink 的prompt.transientCmd 下依赖 Clink 提供的瞬态支持。一次性执行clink set prompt.transient value即可value可取always总是替换上一条提示符same_dir仅当工作目录与上一条命令结束时相同才替换off不替换即关闭瞬态随后编辑starship.lua定制左右两侧显示内容左侧默认替换为。定义starship_transient_prompt_func函数自定义该函数会收到当前提示符字符串。例如显示character模块注意通过rl.getvariable(keymap)把按键映射信息传给starship module使字符随 vi/emacs 模式变化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_transient_prompt_func/starship_transient_rprompt_func是否已定义若已定义则把它们挂接到 Clink 的transientfilter/transientrightfilter提示符过滤器上。3. Fishenable_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.fishenable_transience为回车键绑定__starship_transient_execute该函数先检查commandline --is-valid且输入非空再设置TRANSIENT/RIGHT_TRANSIENT标志并触发 repaintfish_prompt与fish_right_prompt在标志生效时分别调用starship_transient_prompt_func与starship_transient_rprompt_func未定义时回退到默认❯或空字符串并在fish_postexec事件中自动复位标志。此外若 Fish 版本 ≥ 4.1脚本会改用 Fish 内建的fish_transient_prompt机制。4. Bash基于 Ble.sh 的瞬态支持Bash 自身没有瞬态机制需要安装Ble.sh v0.4 及以上的框架官方仓库。在~/.bashrc中设置bleopt prompt_ps1_transientvalue启用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中定制左右两侧左侧配置 Ble.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在提示符绘制之前或命令执行之前插入自定义逻辑是高级定制的另一大需求。各 Shell 支持程度不同1. CmdClink 的灵活钩子 APIClink 为 Cmd 提供了非常灵活的 pre-prompt 与 pre-exec 钩子与 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则在starship_prompt:filter中、真正渲染 Starship 提示符之前被调用。2. Bashstarship_precmd_user_func与 DEBUG trapBash 不像多数 Shell 那样有正式的 preexec/precmd 框架因此难以提供完全可定制的钩子但 Starship 仍给出了有限的注入点提示符绘制前定义一个函数再把函数名赋给starship_precmd_user_func。例如function blastoff(){ echo } starship_precmd_user_funcblastoff命令执行前借助 Bash 的DEBUGtrap 机制。但必须在初始化 Starship 之前设置 DEBUG trapStarship 可以保留 DEBUG trap 的值但如果 trap 在 Starship 启动后被覆盖部分功能会失效function blastoff(){ echo } trap blastoff DEBUG # Trap DEBUG *before* running starship set -o functrace eval $(starship init bash) set o functrace3. PowerShellInvoke-Starship-PreCommandPowerShell 同样缺少正式的 preexec/precmd 框架Starship 提供的入口是名为Invoke-Starship-PreCommand的函数function Invoke-Starship-PreCommand { $host.ui.Write() }在 src/init/starship.ps1 的global:prompt函数中每次渲染提示符前都会检测Test-Path function:Invoke-Starship-PreCommand存在则调用——这也是下面窗口标题联动在 PowerShell 中的实现入口。三、窗口标题联动Change Window Title部分 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 中把该函数设置为 precmd 函数starship_precmd_user_funcset_win_title在 zsh 中把它加入precmd_functions数组precmd_functions(set_win_title)效果满意后把上述行追加到~/.bashrc或~/.zshrc使其永久生效。例如在终端标签页标题显示当前目录名function set_win_title(){ echo -ne \033]0; $(basename $PWD) \007 } starship_precmd_user_funcset_win_titleCmd下可通过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函数实现类似效果# edit $PROFILE function Invoke-Starship-PreCommand { $host.ui.RawUI.WindowTitle $env:USERNAME$env:COMPUTERNAME: $pwd a } Invoke-Expression (starship init powershell)四、启用右侧提示Right Prompt部分 Shell 支持与输入在同一行渲染的右侧提示。Starship 通过right_format配置项设置其内容任何可用于format的模块都可以用于right_format$all变量只包含未在format或right_format中显式使用的模块。注意右侧提示是与输入位置同一行的单行内容。若要在多行提示符中把模块右对齐到输入行的上方请参考fill模块。right_format目前支持以下 Shellelvish、fish、zsh、xonsh、cmd、nushell、bash。其中 Bash 需要先安装 Ble.sh v0.4 及以上版本才能使用右侧提示。示例# ~/.config/starship.toml # A minimal left prompt format $character # move the rest of the prompt to the right right_format $all效果类似▶ starship on  rprompt [!] is v0.57.0 via v1.54.0 took 17szsh 注意事项zshv5.0.5会给右侧提示默认追加一个尾随空格在使用$fill模块时可能导致对齐问题。在.zshrc中添加以下配置消除该间隙ZLE_RPROMPT_INDENT0从实现看右侧提示由 CLI 的--right标志驱动在 src/main.rs 中right参数与标准左侧提示互斥Fish 的fish_right_promptsrc/init/starship.fish与 Clink 的rightfiltersrc/init/starship.lua都通过starship prompt --right ...调用底层渲染。五、续行提示Continuation Prompt当用户输入了不完整的语句例如单独的左括号或引号时部分 Shell 会渲染一个与常规提示符不同的续行提示符。Starship 通过continuation_prompt配置项设置它默认值为∙ 。注意continuation_prompt必须设置为不含任何变量的字面字符串。注意续行提示仅在以下 Shell 中可用bash、zsh、PowerShell。示例# ~/.config/starship.toml # A continuation prompt that displays two filled-in arrows continuation_prompt ▶▶ 在 PowerShell 中该配置由 src/init/starship.ps1 初始化时通过Set-PSReadLineOption -ContinuationPrompt (...)应用——它调用starship prompt --continuation取得渲染结果并设置为 PSReadLine 的续行提示。六、为 Claude Code 定制状态栏StatuslineStarship 支持在 Anthropic 的交互式编码 CLI 工具Claude Code内部显示自定义状态栏Statusline实时展示 Claude 会话的关键信息当前使用的模型、上下文窗口占用情况、会话花费等。1. 启用 Setup在 Claude Code 中运行/statusline并请它配置 Starship或手动把以下内容加入.claude/settings.json{ statusLine: { type: command, command: starship statusline claude-code } }随后在~/.config/starship.toml中定制状态栏外观见下文配置节。2. 工作原理 Overview当以starship statusline claude-code调用时Starship 通过stdin 接收 Claude Code 的会话数据JSON并使用名为claude-code的专用 profile 渲染状态栏。该 profile 包含三个专用模块claude_model显示当前使用的 Claude 模型claude_context以可视化量表gauge显示上下文窗口占用claude_cost显示会话花费与统计信息默认 profile 格式为[profiles] claude-code $claude_model$git_branch$claude_context$claude_cost从源码结构看stdin 数据由 src/utils/statusline.rs 中的ClaudeCodeData结构体解析包含modelid 与 display_name、context_window窗口大小、输入/输出 token 总量、已用百分比、最近一次 API 调用的 token 使用明细、cost总花费、会话时长、API 时长、增删代码行数、workspace与effort推理强度级别等字段该文件内的单元测试验证了会话启动时null字段的容错解析与完整数据的反序列化。模块渲染逻辑则位于 src/modules/claude_model.rs 等模块文件中只有当上下文携带 Claude Code 数据时才会输出。3. 配置 Configuration通过修改claude-codeprofile 与各模块配置来定制状态栏# ~/.config/starship.toml # Customize the claude-code profile [profiles] claude-code $claude_model$claude_context$claude_cost # Configure individual modules [claude_model] format $symbol$model symbol style bold blue [claude_context] format $gauge $percentage gauge_width 10 [claude_cost] format $symbol$cost symbol 4. Claude Model 模块显示当前会话使用的 Claude 模型。选项 Options选项默认值说明format$symbol$model 模块格式symbol 模型名称前显示的符号stylebold blue模块样式model_aliases{}模型 ID 或显示名称到短别名的映射优先按 ID 匹配再按显示名称匹配disabledfalse禁用claude_model模块变量 Variables变量示例说明modelClaude 3.5 Sonnet当前模型的显示名称model_idclaude-3-5-sonnet模型 IDsymbol镜像选项symbol的值style*镜像选项style的值*该变量只能作为样式字符串的一部分使用。示例 Examples# ~/.config/starship.toml # Basic customization [claude_model] format on $symbol$model symbol style bold cyan # Using model aliases for vendor-specific model names # You can alias by model ID or display name [claude_model.model_aliases] # Alias by vendor model ID (e.g. AWS Bedrock) global.anthropic.claude-sonnet-4-5-20250929-v1:0 Sonnet 4.5 # Alias by display name Claude Sonnet 4.5 (Vendor Proxy) Sonnet别名的匹配逻辑与上述文档描述一致在 src/modules/claude_model.rs 中先尝试按model.id查model_aliases未命中再按display_name查最后回退到原始显示名称该模块的测试用例分别覆盖了按 ID 别名、按显示名称别名、无别名回退以及effort推理强度变量的渲染。5. Claude Context 模块以百分比和可视化量表显示上下文窗口占用样式会根据可配置的阈值自动切换。选项 Options选项默认值说明format$gauge $percentage 模块格式symbol量表前显示的符号gauge_width5量表宽度字符数gauge_full_symbol█量表已填充段使用的符号gauge_partial_symbol▒量表部分填充段使用的符号gauge_empty_symbol░量表空段使用的符号display见下文阈值与样式配置disabledfalse禁用claude_context模块Displaydisplay是定义不同占用级别的阈值与样式的对象数组。模块采用匹配到的最高阈值对应的样式若该配置hidden为true则隐藏模块。选项默认值说明threshold0.0匹配该配置所需的最小上下文占用百分比stylebold green匹配该显示配置时使用的style值hiddenfalse匹配该配置时隐藏模块[[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以上默认阈值0 隐藏 / 30 绿 / 60 黄 / 80 红在 src/configs/claude_context.rs 的Default实现中即可确认同时可见默认format、symbol为空、gauge_width为 5 等全部默认值。变量 Variables变量示例说明gauge██▒░░上下文占用的可视化表示percentage65%上下文占用百分比input_tokens45.2k会话累计输入 token 数output_tokens12.3k会话累计输出 token 数curr_input_tokens5.1k最近一次 API 调用的输入 token 数curr_output_tokens1.2k最近一次 API 调用的输出 token 数curr_cache_creation_tokens1.5k最近一次 API 调用的缓存创建 token 数curr_cache_read_tokens23.4k最近一次 API 调用的缓存读取 token 数total_tokens200k上下文窗口总大小symbol镜像选项symbol的值style*镜像匹配到的显示阈值对应的样式*该变量只能作为样式字符串的一部分使用。示例 Examples仅量表的最简显示# ~/.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 red6. Claude Cost 模块以美元显示当前 Claude Code 会话的总花费与claude_context一样支持基于阈值的样式切换。选项 Options选项默认值说明format$symbol(\\$$cost) 模块格式symbol 花费前显示的符号display见下文阈值与样式配置disabledfalse禁用claude_cost模块Displaydisplay是定义花费阈值与样式的对象数组规则同claude_context采用匹配到的最高阈值的样式hidden为true时隐藏模块。选项默认值说明threshold0.0匹配该配置所需的最小花费美元stylebold green匹配该显示配置时使用的style值hiddenfalse匹配该配置时隐藏模块默认配置[[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该默认配置同样可以直接在 src/configs/claude_cost.rs 的Default实现中核对。变量 Variables变量示例说明cost1.23会话总花费美元保留两位小数duration1m 30s会话总时长api_duration45sAPI 调用总时长lines_added1.2k新增代码总行数lines_removed500删除代码总行数symbol镜像选项symbol的值style*镜像匹配到的显示阈值对应的样式*该变量只能作为样式字符串的一部分使用。示例 Examples# ~/.config/starship.toml # Cost with code change statistics [claude_cost] format $symbol$cost ($lines_added -$lines_removed) # Hide module until cost exceeds $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 # Show duration information [claude_cost] format $symbol$cost ($duration) 七、样式字符串Style Strings语法样式字符串是以空白分隔的一组单词单词不区分大小写例如bold与BoLd被视为同一个词。每个单词可以是bolditalicunderlinedimmedinvertedblinkhiddenstrikethroughbg:colorfg:colorcolornone其中color是颜色说明符见下文。目前fg:color与color效果相同但未来可能改变。color还可以设置为prev_fg或prev_bg分别解析为前一个元素的前景色或背景色若可用否则为none。inverted会交换背景色与前景色。字符串中单词的顺序无关紧要。none记号会覆盖字符串中的其他所有记号只要它不是bg:说明符的一部分例如fg:red none fg:blue最终会生成一个无样式的字符串。bg:none将背景设为默认色因此fg:red bg:none等价于red或fg:redbg:green fg:red bg:none也等价于fg:red或red。未来版本中none与其他记号混用可能变为错误。颜色说明符可以是以下任意一种标准终端颜色之一black、red、green、blue、yellow、purple、cyan、white可加bright-前缀获得亮色版本如bright-white。以#开头的六位十六进制数表示 RGB 颜色十六进制码。0–255 之间的数字表示 8-bit ANSI 颜色码。如果前景/背景指定了多个颜色字符串中最后一个颜色优先。并非所有终端都能正确显示所有样式已知问题包括许多终端默认禁用blink支持。hidden在 iTerm 上不受支持。strikethrough不受 macOS 默认 Terminal.app 支持。结语以上便是 Starship 在starship.toml常规配置之外的全部高级定制手段瞬态提示符让历史提示符让位于当前输入pre-prompt / pre-exec 钩子让提示符渲染与命令执行前后可以注入任意逻辑窗口标题联动与右侧提示、续行提示补齐了日常体验细节Claude Code 状态栏则把 Starship 的模块化渲染能力延伸到了 AI 编码工具内部。所有钩子函数名均为约定式命名实际行为由仓库内对应 Shell 的初始化脚本src/init/ 目录下的starship.ps1、starship.lua、starship.fish等决定因此在不同 Shell 之间迁移配置时只需关注该 Shell 约定的函数名与启用命令即可。若需继续深入可阅读英文原版 docs/advanced-config/README.md 及各模块源码如 src/configs/claude_context.rs、src/configs/claude_cost.rs、src/configs/claude_model.rs、src/utils/statusline.rs获取最新细节。【免费下载链接】starship☄️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考