正心全栈编程
# terminal

Starship 提示符配置 ​

在上一节的 fish 中进入项目目录时，如果提示符只显示路径，就得再执行命令才能确认 Git 分支和文件状态。本节为 fish 加上 Starship：先看到基本提示符，再进入一个练习仓库，观察分支、未跟踪文件和命令结果如何出现在提示符中。

提示符需求与工具分工 ​

Starship 是一个跨 Shell 的命令行提示符工具。

它不负责执行命令，只控制每行命令前面的提示符。比如 Ubuntu 原本可能显示：

text
zhengxin@DESKTOP:~/code$

进入项目并配置 Starship 后，可能变成：

text
zhengxin in ~/code/my-project on  main via 🐍 v3.12.2
❯

Starship 可以按目录和环境显示用户、路径、Git 分支与状态、Python/Node.js 版本、上条命令的耗时及结果。上图只是示意：Git、Python 和 Node.js 模块不会在每个目录同时出现。官方把它定位为快速、可定制、跨 Shell 的提示符，支持 Bash、zsh、fish、PowerShell 等 Shell。

Starship 现代化提示符全景解构与动态上下文嗅探图

终端、Shell 与提示符

本系列使用的工具分工如下：

text
终端窗口：WezTerm / Windows Terminal
命令解释器：Bash / zsh / fish / PowerShell
命令提示符：Starship

例如以下组合都可以使用：

text
WezTerm + WSL Ubuntu + zsh + Starship
WezTerm + WSL Ubuntu + fish + Starship
Windows Terminal + PowerShell + Starship

项目状态

默认提示符通常只有用户名、主机名和目录。开发时还要确认当前 Git 分支、Python 虚拟环境、Node.js 版本，以及上一条命令是否失败、运行了多久；Starship 可以把满足显示条件的信息放进提示符。

跨 Shell 配置

同时使用 Bash、zsh、fish 或 PowerShell 时，分别手写提示符配置比较费事。

Starship 的优点是：同一系统中的多个 Shell 可以共用一份 starship.toml 配置。每个 Shell 仍需分别加入初始化命令；Windows 和 WSL Ubuntu 也有各自的安装环境与配置文件。

在 WSL Ubuntu 中，默认配置文件是 ~/.config/starship.toml。

配置成本

zsh 生态中有 oh-my-zsh、powerlevel10k、zinit、antigen 等工具，各有用途，但组合配置的步骤较多。Starship 这一路线只需安装程序、在 Shell 中初始化，再编辑 starship.toml。

安装与初始化 ​

WSL Ubuntu 安装 ​

本系列在 WSL Ubuntu 的 fish 中继续操作。先在 WSL Ubuntu 中安装 Starship：

bash
curl -sS https://starship.rs/install.sh | sh
starship --version

能输出版本号，表示当前 WSL 环境已能找到 starship。Ubuntu 25.04 及以后也可以通过 apt install starship 安装；Ubuntu 24.04 按上面的官方脚本操作即可。

fish 初始化 ​

编辑：

fish
nano ~/.config/fish/config.fish

加入：

fish
starship init fish | source

这是官方推荐的 fish 初始化方式。保存后重新进入 fish，或在当前 fish 中执行：

fish
source ~/.config/fish/config.fish

提示符发生变化，说明初始化已生效；此时尚未创建 starship.toml，看到的是默认样式。一个 Shell 只需要添加一次初始化命令，避免每次加载配置时重复执行。

Bash 与 PowerShell 配置 ​

Bash：编辑 ~/.bashrc，加入：

bash
eval "$(starship init bash)"

保存后新开 Bash 会话，观察提示符是否变化。

Windows PowerShell：如果在 Windows 侧使用 Starship，可以用 winget 安装。Windows 安装不会替代上面 WSL Ubuntu 中的安装：

powershell
winget install --id Starship.Starship

官方文档也列出了 Scoop、Chocolatey、MSI 等安装方式。安装后先确保 PowerShell 配置目录存在，再打开配置文件：

powershell
New-Item -ItemType Directory -Force -Path (Split-Path $PROFILE) | Out-Null
notepad $PROFILE

加入：

powershell
Invoke-Expression (&starship init powershell)

保存后重启 PowerShell，执行 starship --version 并观察提示符。

Starship 跨 Shell 统一架构与配置文件流转链路图

基础配置与效果验证 ​

基础配置 ​

创建配置文件：

fish
mkdir -p ~/.config
touch ~/.config/starship.toml

官方默认配置路径就是：

text
~/.config/starship.toml

先把下面的简版配置写入 ~/.config/starship.toml：

toml
# ~/.config/starship.toml

add_newline = true

format = """
$directory$git_branch$git_status$python$nodejs$cmd_duration
$character
"""

[directory]
truncation_length = 3
truncate_to_repo = true

[git_branch]
symbol = " "

[python]
symbol = "🐍 "
format = "via [$symbol$version]($style) "

[nodejs]
symbol = " "
format = "via [$symbol$version]($style) "

[cmd_duration]
min_time = 1000
format = "took [$duration]($style) "

[character]
success_symbol = "[❯](bold green)"
error_symbol = "[❯](bold red)"

Git 状态与命令结果验证 ​

保存配置后，在 fish 中按回车生成新提示符。接着准备一个可以观察 Git 模块的目录：

fish
mkdir -p ~/starship-demo
cd ~/starship-demo
git init -b main
printf 'Starship demo\n' > demo.txt
git status --short

git status --short 应显示 ?? demo.txt。此时提示符应显示 starship-demo、main，并由 Git 状态模块提示存在未跟踪文件。Git 状态的符号和颜色取决于当前配置；如果仓库干净，状态模块可能没有可见内容。

再执行一条超过一秒的命令，观察耗时模块：

fish
sleep 2

在下一次提示符中应看到约 2s 的耗时信息；随后输入 false，观察输入符号由绿色变为红色。false 是用于验证失败状态的命令，不需要修复；执行 true 可让下一次提示符恢复成功状态。

在 Git 仓库、已激活的 Python 环境或能识别 Node.js 项目的目录中，提示符可能进一步显示相应模块，例如：

text
~/code/demo on  main via 🐍 v3.12.2 via  v22.0.0 took 2s
❯

这里的版本号与耗时只是示意，学员机器上的输出以实际环境为准。没有进入对应项目或没有启用相关环境时，不必为了匹配示意输出而安装 Python 或 Node.js。

配置项速查 ​

format

决定提示符显示哪些模块、按什么顺序显示。

toml
format = """
$directory$git_branch$git_status$python$nodejs
$character
"""

你可以理解为：提示符总布局。

right_format

右侧提示符。

例如：

toml
format = "$directory$git_branch$character"
right_format = "$cmd_duration$time"

部分 Shell 支持右提示符，Starship 官方文档说明 right_format 可用于 fish、zsh、cmd、nushell、bash 等，不过 bash 右提示符需要额外条件。

add_newline

是否在两次提示符之间加空行。

toml
add_newline = true

想紧凑一点可以改成：

toml
add_newline = false

[directory]

控制目录显示。

toml
[directory]
truncation_length = 3
truncate_to_repo = true

这个适合项目路径很长的情况。

[character]

控制输入符号。

toml
[character]
success_symbol = "[❯](bold green)"
error_symbol = "[❯](bold red)"

成功时绿色，失败时红色。

[cmd_duration]

显示命令耗时。

toml
[cmd_duration]
min_time = 1000
format = "took [$duration]($style) "

表示命令执行超过 1 秒才显示耗时。

starship.toml 模板语法与终端视觉效果点对点映射图

完整配置 ​

熟悉简版配置后，可以用下面的完整配置替换 ~/.config/starship.toml 的内容。保留目录、Git 分支与状态、语言版本、Shell、命令耗时和右侧时间，并额外显示用户与主机名：

toml
# ~/.config/starship.toml
format = """
$username$hostname$directory$git_branch$git_status$python$nodejs$shell$cmd_duration
$character"""

right_format = "$time"
add_newline = true  # 在两次提示符之间添加空行

[shell]
disabled = false
bash_indicator = "bash"
fish_indicator = "fish"
style = "cyan bold"
format = "with [$indicator]($style) "

[directory]
truncation_length = 3
truncate_to_repo = true
style = "bold cyan"

[git_branch]
symbol = " "
format = "on [$symbol$branch]($style) "
style = "bold purple"

[python]
symbol = "🐍 "
format = "via [$symbol$version]($style) "
style = "bold yellow"

[nodejs]
symbol = " "
format = "via [$symbol$version]($style) "
style = "bold green"

[username]
show_always = true
format = "[$user]($style)@"

[hostname]
ssh_only = false
format = "[$hostname]($style) "

[git_status]
style = "red"

[character]
success_symbol = "[❯](green)"
error_symbol = "[❯](red)"

[time]
disabled = false
time_format = "%Y-%m-%d %H:%M:%S"
format = "$time "

保存后按回车刷新提示符。回到 ~/starship-demo 时应能看到用户、主机、目录、Git 分支及未跟踪文件状态；右侧时间仅在当前 Shell 支持右提示符时显示。$git_status 和 $hostname 已写进 format，因此下方对应模块的设置才会参与显示。

常见问题 ​

命令结果与耗时状态反馈闭环及 Nerd Font 乱码排查图

初始化后提示符未变化 ​

先执行 starship --version，确认当前 Shell 能找到程序；再核对初始化命令是否写在当前使用的 Shell 配置文件中。fish 使用 ~/.config/fish/config.fish，Bash 使用 ~/.bashrc，Windows PowerShell 使用 $PROFILE。保存后新开对应 Shell；fish 也可以执行 source ~/.config/fish/config.fish。

Windows PowerShell 与 WSL Ubuntu 是两套环境。只在 Windows 安装 Starship，不会让 WSL 中的 fish 自动获得该命令。

Git 或语言模块未显示 ​

先检查是否进入 Git 仓库：git status --short 能显示 ?? demo.txt，才有未跟踪文件可供状态模块展示。再检查 format 是否包含 $git_branch、$git_status 等模块名。Python 和 Node.js 模块也需要对应的目录或环境条件，普通空目录不会显示全部模块。

提示符图标乱码 ​

原因通常是终端字体没有设置 Nerd Font。

解决：

text
安装 Nerd Font
把 WezTerm / Windows Terminal 字体改成对应 Nerd Font
重启终端

fish 初始化语法错误 ​

fish 启用 Starship 是：

fish
starship init fish | source

不是：

bash
eval "$(starship init fish)"

config.fish 负责启用 Starship，starship.toml 决定提示符显示什么。回到练习仓库后，可用 Git 文件状态、命令耗时和失败状态核对配置效果。