企业官网建设流程全解析

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. PowerShell：Enable-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. Cmd：Clink 的prompt.transient

Cmd 下依赖 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. Fish：enable_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：enable_transience为回车键绑定__starship_transient_execute，该函数先检查commandline --is-valid且输入非空，再设置TRANSIENT/RIGHT_TRANSIENT标志并触发 repaint；fish_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_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）中定制左右两侧：

• 左侧：配置 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. Cmd：Clink 的灵活钩子 API

Clink 为 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. Bash：starship_precmd_user_func与 DEBUG trap

Bash 不像多数 Shell 那样有正式的 preexec/precmd 框架，因此难以提供完全可定制的钩子，但 Starship 仍给出了有限的注入点：

• 提示符绘制前：定义一个函数，再把函数名赋给starship_precmd_user_func。例如：

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

• 命令执行前：借助 Bash 的DEBUGtrap 机制。但必须在初始化 Starship 之前设置 DEBUG trap！Starship 可以保留 DEBUG trap 的值，但如果 trap 在 Starship 启动后被覆盖，部分功能会失效：

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

3. PowerShell：Invoke-Starship-PreCommand

PowerShell 同样缺少正式的 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_func="set_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_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函数实现类似效果：

# 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目前支持以下 Shell：elvish、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 17s

zsh 注意事项：zsh（v5.0.5+）会给右侧提示默认追加一个尾随空格，在使用$fill模块时可能导致对齐问题。在.zshrc中添加以下配置消除该间隙：

ZLE_RPROMPT_INDENT=0

从实现看，右侧提示由 CLI 的--right标志驱动：在 src/main.rs 中，right参数与标准左侧提示互斥，Fish 的fish_right_prompt（src/init/starship.fish）与 Clink 的rightfilter（src/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 定制状态栏（Statusline）

Starship 支持在 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结构体解析，包含model（id 与 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

变量 Variables

*：该变量只能作为样式字符串的一部分使用。

示例 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

Display

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

[[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

*：该变量只能作为样式字符串的一部分使用。

示例 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 red"

6. Claude Cost 模块

以美元显示当前 Claude Code 会话的总花费，与claude_context一样支持基于阈值的样式切换。

选项 Options

Display

display是定义花费阈值与样式的对象数组，规则同claude_context：采用匹配到的最高阈值的样式，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"

该默认配置同样可以直接在 src/configs/claude_cost.rs 的Default实现中核对。

变量 Variables

*：该变量只能作为样式字符串的一部分使用。

示例 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被视为同一个词）。每个单词可以是：

• 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记号会覆盖字符串中的其他所有记号（只要它不是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 颜色十六进制码。
• 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