Starship Prompt 完全指南 2026：跨 Shell 自定义、模块与预设主题

终端提示符是你开发流程中查看次数最多的文本。它每天向你问好数千次，但大多数开发者使用的默认提示符只显示一个美元符号和一个路径。一个优秀的提示符能告诉你当前所在分支、是否有未提交的更改、活跃的语言运行时版本以及目标云上下文 — 而无需运行任何命令。

Starship 是解决所有提示符困扰的答案。用 Rust 编写以确保速度，为跨 Shell 兼容而设计，通过单个 TOML 文件配置，Starship 已成为现代开发者的事实标准提示符。本指南涵盖从安装到高级自定义的所有内容，提供可以直接复制到 starship.toml 中的真实配置示例。

什么是 Starship 以及为什么它很重要

Starship 是一个用 Rust 编写的开源跨 Shell 提示符。它用上下文感知的、信息丰富的提示符替换默认 Shell 提示符，自动适应当前项目。进入 Node.js 项目，Starship 显示 Node 版本。切换到 Python 虚拟环境，它显示环境名称。检出 Git 分支，它显示分支名以及领先/落后计数、暂存更改和未跟踪文件。

为什么跨 Shell 提示符很重要？开发者经常在不同 Shell 之间切换 — 远程服务器上的 Bash、macOS 上的 Zsh、个人机器上的 Fish、Windows 工作站上的 PowerShell。像 Oh My Zsh 这样特定于 Shell 的提示符框架只在一种 Shell 中工作。Starship 在所有地方都使用相同的配置、相同的外观和相同的行为。

• 跨 Shell：一个配置文件适用于 Bash、Zsh、Fish、PowerShell、Nushell、Cmd、Elvish、Tcsh、Xonsh
• 极速：用 Rust 编写，即使启用多个模块也能在 10ms 内渲染
• 上下文感知：自动检测 Git、Node、Python、Rust、Go、Java、Docker、Kubernetes、AWS、GCP、Azure
• 单文件配置：所有设置都在 ~/.config/starship.toml 中
• 超过 50 个内置模块带有合理的默认值 — 开箱即用效果很好
• 活跃的社区，拥有 45,000+ GitHub 星标和频繁发布

Starship vs Oh My Zsh vs Powerlevel10k vs Pure

每种提示符工具适合不同的需求。此对比帮助你了解 Starship 的优势以及替代方案可能更适合的场景。

安装

Starship 以单个二进制文件分发。使用你喜欢的方式安装，然后将初始化脚本添加到 Shell 配置中。

Install Script (Linux / macOS)

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

Homebrew (macOS / Linux)

brew install starship

Scoop (Windows)

scoop install starship

Cargo (Rust)

cargo install starship --locked

Package Managers

# Arch Linux
pacman -S starship

# Nix
nix-env -iA nixpkgs.starship

# Conda
conda install -c conda-forge starship

# Termux (Android)
pkg install starship

# Chocolatey (Windows)
choco install starship

# WinGet (Windows)
winget install --id Starship.Starship

Shell 配置（Bash、Zsh、Fish、PowerShell、Nushell、Cmd、Elvish、Tcsh、Xonsh）

安装 Starship 二进制文件后，你需要在 Shell 配置文件中添加一行来激活它。以下是每个支持的 Shell 的初始化命令。

Bash (~/.bashrc)

eval "$(starship init bash)"

Zsh (~/.zshrc)

eval "$(starship init zsh)"

Fish (~/.config/fish/config.fish)

starship init fish | source

PowerShell ($PROFILE)

Invoke-Expression (&starship init powershell)

Nushell

# In env.nu
mkdir ~/.cache/starship
starship init nu | save -f ~/.cache/starship/init.nu

# In config.nu
use ~/.cache/starship/init.nu

Other Shells

# Cmd (via Clink) — starship.lua in Clink scripts directory
load(io.popen('starship init cmd'):read("*a"))()

# Elvish (~/.elvish/rc.elv)
eval (starship init elvish)

# Tcsh (~/.tcshrc)
eval `starship init tcsh`

# Xonsh (~/.xonshrc)
execx($(starship init xonsh))

starship.toml 配置基础

所有 Starship 配置都在 ~/.config/starship.toml 中（或通过 STARSHIP_CONFIG 环境变量设置的路径）。该文件使用 TOML 格式，包含整体提示符格式和各个模块的配置节。

顶层 format 键定义提示符布局。每个模块有自己的配置节，包含 format、style、symbol 和 disabled 等选项。你还可以在顶层设置 scan_timeout 和 command_timeout 来控制性能。

# ~/.config/starship.toml

# Top-level prompt format
format = """
\$directory\
\$git_branch\
\$git_status\
\$nodejs\
\$python\
\$rust\
\$docker_context\
\$cmd_duration\
\$line_break\
\$character"""

# Timeout for scanning directories (milliseconds)
scan_timeout = 30

# Timeout for commands run by modules
command_timeout = 500

# Blank line between prompts
add_newline = true

# Prompt character
[character]
success_symbol = "[>](bold green)"
error_symbol = "[>](bold red)"

模块系统概览

Starship 使用模块化架构。提示符中的每条信息都是一个模块 — git_branch、nodejs、python、directory 等。模块仅在相关时显示：nodejs 模块仅在当前目录树中检测到 package.json 或 .node-version 文件时才出现。

默认格式字符串以合理的顺序包含所有内置模块。你可以覆盖它来重新排序模块、移除不需要的模块或添加自定义模块。每个模块支持格式字符串，精确控制显示的文本和符号。

# Disable a module entirely
[package]
disabled = true

# Customize module format
[nodejs]
format = "via [Node \$version](bold green) "

# Change module symbol
[python]
symbol = "py "
format = 'via [\${symbol}\${pyenv_prefix}(\${version})(\(\$virtualenv\))](bold yellow) '

Git 状态模块

Git 模块是 Starship 最受欢迎的功能。git_branch 模块显示当前分支名和可自定义的符号。git_status 模块显示工作树状态的紧凑摘要：暂存、修改、未跟踪、删除、重命名和贮藏计数，加上相对于上游分支的领先/落后信息。

你可以自定义 git_status 中的每个符号。默认符号简洁，但你可以用 Nerd Font 图标或表情替换它们以获得更直观的体验。git_commit 模块在分离 HEAD 状态下显示当前提交哈希，git_state 显示你是否正在进行变基、合并、摘取或二分查找。

[git_branch]
symbol = " "        # Nerd Font branch icon
style = "bold purple"
format = "on [\$symbol\$branch(:$remote_branch)](\$style) "

[git_status]
ahead = "A\${count} "
behind = "B\${count} "
diverged = "D\${ahead_count}/\${behind_count} "
staged = "+\${count} "
modified = "!\${count} "
untracked = "?\${count} "
deleted = "x\${count} "
stashed = "*\${count} "
style = "bold red"

[git_commit]
commit_hash_length = 7
tag_symbol = " "

[git_state]
rebase = "REBASING"
merge = "MERGING"
cherry_pick = "CHERRY-PICKING"

Visual prompt example showing Git status in action:

# Clean branch, ahead of remote by 2 commits
~/projects/myapp on  main A2 
> 

# Branch with staged and modified files
~/projects/myapp on  feature/auth +3 !2 ?1 
> 

# Detached HEAD during interactive rebase
~/projects/myapp on  a3f7c21 REBASING 3/5
> 

语言检测模块

Starship 包含几乎所有编程语言和运行时的模块。每个语言模块检测特定文件（如 Node.js 的 package.json、Rust 的 Cargo.toml 或 Python 的 pyproject.toml）并显示活跃版本。在切换需要不同运行时版本的项目时，这非常有用。

你可以为每个语言模块自定义符号、样式和版本格式。detect_files、detect_folders 和 detect_extensions 选项让你精细调整每个模块何时激活。

# Node.js — detects package.json, .node-version, .nvmrc
[nodejs]
format = "via [ \$version](bold green) "
detect_files = ["package.json", ".node-version"]
detect_extensions = ["js", "mjs", "cjs", "ts", "mts"]

# Python — detects pyproject.toml, requirements.txt, .python-version
[python]
format = 'via [\${symbol}\${pyenv_prefix}(\${version})(\(\$virtualenv\))](bold yellow) '
symbol = " "

# Rust — detects Cargo.toml
[rust]
format = "via [ \$version](bold red) "

# Go — detects go.mod, go.sum, .go files
[golang]
format = "via [ \$version](bold cyan) "

# Java — detects pom.xml, build.gradle, .java files
[java]
format = "via [ \$version](bold red) "

# Ruby — detects Gemfile, .ruby-version
[ruby]
format = "via [ \$version](bold red) "

# PHP — detects composer.json, .php files
[php]
format = "via [ \$version](bold purple) "

云和 Kubernetes 模块

对于 DevOps 和云工程师，Starship 提供 AWS、Google Cloud、Azure 和 Kubernetes 模块。aws 模块读取 AWS_PROFILE 和区域，gcloud 模块显示活跃的 GCP 项目和区域，kubernetes 模块显示 kubeconfig 中的当前集群和命名空间。

这些模块默认禁用，以避免对不使用云 CLI 的开发者造成性能开销。在需要时在 starship.toml 中启用它们。

# AWS — reads AWS_PROFILE and region
[aws]
disabled = false
format = 'on [\$symbol(\$profile)(\(\$region\))](bold yellow) '
symbol = " "

[aws.region_aliases]
us-east-1 = "use1"
eu-west-1 = "euw1"

# Google Cloud
[gcloud]
disabled = false
format = 'on [\$symbol\$account(@\$domain)(\(\$region\))](bold blue) '
symbol = " "

# Azure
[azure]
disabled = false
format = "on [ \$subscription](bold blue) "

# Kubernetes — shows cluster and namespace
[kubernetes]
disabled = false
format = 'on [ \$context(\(\$namespace\))](bold purple) '

[kubernetes.context_aliases]
"arn:aws:eks:us-east-1:123456789:cluster/prod" = "prod"
"gke_myproject_us-central1_staging" = "staging"

Docker 上下文模块

docker_context 模块显示当前 Docker 上下文，这在切换本地开发、远程 Docker 主机和容器编排平台时至关重要。它仅在上下文不是默认值时出现，减少提示符噪音。

[docker_context]
format = "via [ \$context](bold blue) "
only_with_files = true
detect_files = ["docker-compose.yml", "docker-compose.yaml", "Dockerfile"]
detect_extensions = ["dockerfile"]

目录模块自定义

目录模块控制当前路径的显示方式。默认情况下，Starship 将长路径截断为三个父目录。你可以自定义截断长度、截断符号、替换（用短别名替换长路径如 ~/Developer/projects），以及是否在缺少写权限的目录显示只读符号。

[directory]
truncation_length = 4
truncation_symbol = ".../""
truncate_to_repo = true
read_only = " "
style = "bold cyan"

# Path substitutions for shorter display
[directory.substitutions]
"~/Developer/projects" = "DEV"
"~/Documents/work" = "WORK"
"~/.config" = "CFG"

自定义模块

自定义模块让你在提示符中显示任何 Shell 命令输出。这是 Starship 针对内置模块未覆盖的信息的扩展机制。使用 command、when 条件和 format 字符串定义自定义模块。Starship 根据 command_timeout 设置缓存输出。

常见的自定义模块用例包括显示当前 Terraform 工作区、显示活跃的 tmux 会话、显示后台作业数或指示 VPN 连接状态。

# Show current Terraform workspace
[custom.terraform]
command = "terraform workspace show"
when = "test -f main.tf"
format = "via [TF \$output](bold purple) "
shell = ["bash", "--noprofile", "--norc"]

# Show active tmux session
[custom.tmux]
command = "tmux display-message -p '#S' 2>/dev/null"
when = "test -n \"\$TMUX\""
format = "[ \$output](bold yellow) "

# VPN status indicator
[custom.vpn]
command = "echo connected"
when = "pgrep -x openvpn"
format = "[ VPN](bold green) "

命令耗时和执行时间

cmd_duration 模块显示上一条命令的执行时间。默认仅在命令超过 2 秒时显示，保持快速命令的提示符整洁。你可以自定义阈值、格式以及是否显示毫秒精度。

[cmd_duration]
min_time = 2_000          # Show only for commands > 2s
format = "took [\$duration](bold yellow) "
show_milliseconds = false
show_notifications = true  # Desktop notification for long commands
min_time_to_notify = 30_000  # Notify if > 30s

电池模块

电池模块显示当前电池电量和充电状态。对于不想查看系统托盘的笔记本用户很有用。你可以为每个电池电量范围定义自定义阈值、不同的符号和样式。

[battery]
full_symbol = " "
charging_symbol = " "
discharging_symbol = " "

[[battery.display]]
threshold = 15
style = "bold red"

[[battery.display]]
threshold = 50
style = "bold yellow"

[[battery.display]]
threshold = 100
style = "bold green"

时间和用户名模块

时间模块以可配置的格式显示当前时间。默认禁用，但对于想在终端历史中加时间戳的开发者很有用。用户名模块显示当前用户，在 SSH 到远程服务器时确认登录用户身份特别有帮助。

[time]
disabled = false
format = "at [ \$time](bold dimmed white) "
time_format = "%H:%M"
utc_time_offset = "local"

[username]
show_always = false    # Only show on SSH or root
style_root = "bold red"
style_user = "bold yellow"
format = "[\$user]($style) "

[hostname]
ssh_only = true
format = "on [\$hostname](bold dimmed green) "
trim_at = "."

Nerd Font 图标和符号

Nerd Fonts 是包含数千个图标的修补字体，来自 Font Awesome、Devicons、Octicons 和其他图标集。Starship 默认使用 Nerd Font 符号来显示语言图标、Git 符号和其他字形。要正确显示这些图标，请安装 Nerd Font 并将其设为终端字体。

流行的 Nerd Font 选择包括 FiraCode Nerd Font、JetBrainsMono Nerd Font 和 Hack Nerd Font。如果你不想使用 Nerd Fonts，Starship 提供纯文本预设，将所有图标替换为普通 ASCII 字符。

# Install Nerd Font on macOS
brew install --cask font-fira-code-nerd-font
brew install --cask font-jetbrains-mono-nerd-font

# Switch to text-only symbols (no Nerd Font needed)
starship preset plain-text-symbols -o ~/.config/starship.toml

颜色和样式自定义

Starship 样式使用组合前景色、背景色和文本属性的字符串格式。格式为 "fg:color bg:color attributes"，属性包括 bold、italic、underline、dimmed、inverted 和 strikethrough。颜色可以是标准终端颜色名、十六进制代码或 ANSI 256 色号。

# Style syntax examples
[directory]
style = "bold cyan"                    # Bold cyan foreground

[git_branch]
style = "fg:#a6e3a1 bold"              # Hex color, bold

[nodejs]
style = "fg:green bg:#1e1e2e bold"     # Green on dark background

[cmd_duration]
style = "fg:220 italic"                # ANSI 256 color, italic

# Define reusable color palettes (Starship 1.17+)
palette = "catppuccin_mocha"

[palettes.catppuccin_mocha]
rosewater = "#f5e0dc"
mauve = "#cba6f7"
red = "#f38ba8"
peach = "#fab387"
green = "#a6e3a1"
blue = "#89b4fa"
text = "#cdd6f4"

预设主题

Starship 附带几个内置预设，可完全改变提示符的外观和感觉。使用 starship preset 命令应用预设，它会用预设配置覆盖你的 starship.toml。

你可以将预设作为起点，然后自定义各个模块。preset 命令还支持输出到标准输出，以便在应用前查看配置。

# List all available presets
starship preset --list

# Apply Tokyo Night preset
starship preset tokyo-night -o ~/.config/starship.toml

# Apply Gruvbox Rainbow preset
starship preset gruvbox-rainbow -o ~/.config/starship.toml

# Apply Pastel Powerline preset
starship preset pastel-powerline -o ~/.config/starship.toml

# Apply Nerd Font Symbols preset
starship preset nerd-font-symbols -o ~/.config/starship.toml

# Apply Bracketed Segments preset
starship preset bracketed-segments -o ~/.config/starship.toml

# Apply Plain Text preset (no special fonts needed)
starship preset plain-text-symbols -o ~/.config/starship.toml

# Preview a preset before applying
starship preset tokyo-night

性能对比

提示符性能很重要，因为慢速提示符会让每个命令都感觉迟缓。Starship 用 Rust 编写并针对速度进行了优化。它并行运行每个模块并积极缓存结果。典型渲染时间为 5-15ms，而 Oh My Zsh 主题为 50-200ms，禁用即时提示符的 Powerlevel10k 为 20-50ms。

你可以使用内置的 timings 命令对 Starship 配置进行基准测试，它按模块分解渲染时间，以便识别和禁用慢速模块。

# Benchmark your current Starship config
starship timings

# Example output:
# directory 0.8ms | git_branch 1.2ms | git_status 3.1ms
# nodejs 1.5ms | character 0.1ms | Total 6.7ms

# Optimize: reduce command timeout for slow modules
command_timeout = 200

# Disable modules you do not use
[php]
disabled = true

右侧提示符配置

Starship 在支持右侧提示符的 Shell（Zsh、Fish、PowerShell、Elvish、Nushell）中支持右侧提示符。starship.toml 中的 right_format 键定义右侧显示的内容。常见选择包括时间模块、命令耗时和状态码。

# Right-side prompt configuration
right_format = """
\$cmd_duration\
\$time"""

[cmd_duration]
format = "[\$duration](dimmed yellow)"

[time]
disabled = false
format = "[\$time](dimmed white)"
time_format = "%H:%M:%S"

条件模块

你可以通过组合 detect_files、detect_folders 和 detect_extensions 选项使模块仅在特定目录中出现。自定义模块支持 when 条件，运行 Shell 命令并仅在命令成功（退出码 0）时显示模块。

这对于显示项目特定信息很有用：仅在包含 .tf 文件的目录中显示 Terraform 工作区，或仅在存在 deploy.yaml 时显示自定义部署目标。

# Show Terraform module only in directories with .tf files
[terraform]
format = "via [TF \$version \$workspace](bold purple) "
detect_files = [".terraform", "main.tf"]

# Custom module with when condition
[custom.deploy_target]
command = "cat deploy.yaml | grep target | cut -d: -f2"
when = "test -f deploy.yaml"
format = "deploy:[\$output](bold red) "

# Show Python only for Python projects
[python]
detect_files = ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"]
detect_extensions = []  # Do not trigger on .py files in non-Python projects

与 tmux 和 screen 集成

Starship 在 tmux 和 GNU screen 会话中无缝工作。由于 Starship 修改的是 Shell 提示符（而非终端模拟器），无论使用什么终端复用器，它都能正确渲染。对于 tmux 用户，你可以使用自定义模块在提示符中显示活跃的 tmux 会话名。

# Custom module to show tmux session in prompt
[custom.tmux_session]
command = "tmux display-message -p '#S' 2>/dev/null"
when = "test -n \"\$TMUX\""
format = "[ \$output](bold yellow) "
shell = ["bash", "--noprofile", "--norc"]

# Tip: Add to your format string
# format = "\${custom.tmux_session}\$directory\$git_branch..."

创建和分享预设

要创建可分享的预设，编写包含所有模块配置的 starship.toml，然后直接分享文件或将其托管为 URL。其他人可以使用 starship preset 或将文件复制到配置目录来应用它。Starship 社区维护着用户贡献的预设仓库。

# Share your config directly
cp ~/.config/starship.toml ~/my-starship-preset.toml

# Apply a preset from a URL
curl -sS https://example.com/my-preset.toml \
  -o ~/.config/starship.toml

# Apply a preset from a local file
cp ~/shared-configs/team-preset.toml ~/.config/starship.toml

# Use STARSHIP_CONFIG env var for per-project presets
export STARSHIP_CONFIG=~/projects/myapp/.starship.toml

按场景的常见配置

不同的工作流受益于不同的提示符配置。以下是三种常见开发者角色的优化设置。

Web 开发

# Optimized for web development
format = """
\$directory\
\$git_branch\$git_status\
\$nodejs\
\$bun\
\$deno\
\$docker_context\
\$cmd_duration\
\$line_break\
\$character"""

[nodejs]
format = "via [ \$version](bold green) "

[bun]
format = "via [ \$version](bold white) "

[deno]
format = "via [ \$version](bold green) "

# Disable irrelevant modules
[aws]
disabled = true
[gcloud]
disabled = true
[java]
disabled = true

DevOps / 云工程

# Optimized for DevOps / Cloud Engineering
format = """
\$username\$hostname\$directory\
\$git_branch\$git_status\
\$kubernetes\$aws\$gcloud\$terraform\
\$docker_context\$cmd_duration\
\$line_break\$character"""

[kubernetes]
disabled = false
format = '[ \$context(\(\$namespace\))](bold purple) '

[aws]
disabled = false
format = '[ \$profile(\(\$region\))](bold yellow) '

[terraform]
format = "via [TF \$version \$workspace](bold purple) "

数据科学 / ML

# Optimized for Data Science / ML
format = """
\$directory\$git_branch\$git_status\
\$python\$conda\$julia\$rlang\
\$docker_context\$cmd_duration\
\$line_break\$character"""

[python]
format = 'via [\${symbol}(\${version})(\(\$virtualenv\))](bold yellow) '
symbol = " "

[conda]
format = "via [ \$environment](bold green) "

# Show long-running training times
[cmd_duration]
min_time = 5_000
show_notifications = true

高级用户技巧

• Tip 1: 使用 starship timings 识别慢速模块并优化提示符渲染时间
• Tip 2: 在 Linux 上将 STARSHIP_CACHE 设置为 ramdisk 路径以实现更快的模块缓存
• Tip 3: 使用 env_var 模块显示自定义环境变量，如 API 端点或部署目标
• Tip 4: 组合目录替换为深层项目路径创建短别名
• Tip 5: 使用 status 模块显示失败命令的退出码和信号名
• Tip 6: 在 NFS 或 SSHFS 等慢速文件系统上将 scan_timeout 设为较低值（如 20ms）
• Tip 7: 在信息行和输入行之间添加 line_break 模块以实现双行提示符布局
• Tip 8: 在 starship.toml 中使用 palettes 定义可复用的颜色名以保持主题一致性

常见问题