默认的 robbyrussell 主题，算是 oh-my-zsh 里很多人入坑的第一个主题。绿色的用户名、蓝色的路径、括号里的 git 分支，简单干净，启动也快。我用它当主力主题用了很长一段时间，一直没换，原因就是它足够轻量，配色也耐看。但后来有几个工作流的痛点反复戳我：第一，我在本地终端里几乎不关心用户名和主机名，每行提示符前面那一大串纯属占地方；第二，我希望提示符能告诉我当前 git 仓库有没有未提交的变更，以及上一条命令到底有没有执行成功。这两个信息默认 robbyrussell 都不给。去换了 powerlevel10k 这类重主题，又觉得为了这点需求大动干戈不值当。于是我开始研究怎么直接修改 robbyrussell 主题，把它改成自己的形状。
这篇文章就是一次完整的修改路径记录。我会从主题文件的结构拆解开始，讲清楚每一段转义序列的含义，再带你建立一个自己的自定义主题文件，最后把我的调试方法和踩过的坑也一并写出来。适合刚接触 zsh 配置、又不想被各种重型框架绑住手的人参考。
1. 先拆开 robbyrussell 主题文件，搞清每一行是什么意思
1.1 主题文件在哪，为什么不能直接在原文件上改
主题文件放在 oh-my-zsh 安装目录下的 themes 文件夹里，机器上的路径一般是这样：
echo $ZSH/themes/robbyrussell.zsh-theme默认情况下你大概率会看到类似/home/用户名/.oh-my-zsh/themes/robbyrussell.zsh-theme的路径。这个文件非常短，整个主题的核心代码也就十几行，不像某些花哨主题动辄几百行。这也是 robbyrussell 适合拿来二次修改的原因：逻辑透明，几乎没有什么黑魔法。
有两个地方你从一开始就要记住：
- 这个文件归 oh-my-zsh 管理，
omz update升级时，themes 目录下的文件会被覆盖。你辛辛苦苦改出来的成果，一次升级就可能全部归零。 - oh-my-zsh 留了一个专门的用户自定义目录：
$ZSH_CUSTOM。它默认指向~/.oh-my-zsh/custom，里面的 themes 子目录就是给我们放自定义主题用的。这个目录的优先级高于默认 themes 目录，也不会被升级清理。
所以正确做法不是去改 robbyrussell 原文件，而是把它复制成自己的主题文件，再在副本上动手。后面第 2 部分我会给完整步骤。
1.2 默认主题文件里那几行代码，拆开看就三块内容
标准 robbyrussell 主题文件的内容大致如下：
PROMPT='%{$fg_bold[green]%}%n@%m%{$reset_color%} %{$fg_bold[blue]%}%~%{$reset_color%} $(git_prompt_info)%{$reset_color%} %(!.#.$) ' RPROMPT='' ZSH_THEME_GIT_PROMPT_PREFIX="git:(" ZSH_THEME_GIT_PROMPT_SUFFIX=") " ZSH_THEME_GIT_PROMPT_DIRTY="* " ZSH_THEME_GIT_PROMPT_CLEAN=""看着像乱码，其实逻辑很直白。三块内容分别是：
PROMPT定义了主提示符，也就是每行命令执行前显示的那串内容。RPROMPT定义了右侧提示符，robbyrussell 默认把它留空了，所以右侧什么都不显示。ZSH_THEME_GIT_PROMPT_*这组变量控制git_prompt_info函数输出的格式。
我逐个拆一下 PROMPT 里的组成部分：
%{$fg_bold[green]%}：把接下来的文字设置为“粗体绿色”。fg_bold是 oh-my-zsh 预定义的颜色变量，本质是一个 ANSI 转义序列。外面那层%{...%}是 zsh 的“非打印字符”包裹语法，告诉 zsh“这对花括号里面的内容不会占用屏幕宽度”，这样终端的换行和光标定位才能算对。%n@%m：%n是当前用户名，%m是短格式的主机名，中间用@连起来，这就是你提示符最前面那段用户名@主机名。%{$fg_bold[blue]%}%~%{$reset_color%}：把背景切成蓝色，显示当前目录。%~表示当前目录，并且用~简写家目录，比如你在家目录下Documents文件夹里，会显示~/Documents而不是/home/xxx/Documents。显示完目录后接一个reset_color把颜色恢复正常。$(git_prompt_info)：调用 oh-my-zsh 内置函数git_prompt_info。这个函数会检查当前目录是否位于 git 仓库中，是的话就返回一个分支信息字符串。注意这里用的是命令替换写法，oh-my-zsh 默认开启了PROMPT_SUBST选项，所以它会在每次渲染提示符时重新执行函数，保证分支信息是当前的。%(!.#.$)：zsh 的条件判断写法。%(条件.满足时输出.不满足时输出)，!表示“当前用户是 root”，所以 root 下显示#，普通用户显示$，这也是很多 Linux 终端提示符的经典规则。
RPROMPT 默认是空的，这也是 robbyrussell 看起来特别干净的原因之一。如果你观察过其他主题，会发现很多主题把分支、时间、退出码都放在右侧，robbyrussell 什么都没放，视觉负担很小。
1.3 Git 提示符这些变量的联动作用
再单独说 Git 部分。git_prompt_info不是魔法，它的输出完全由变量拼装。默认情况下它在干净仓库输出：
(git:main)在有未提交修改的脏仓库输出：
(git:main*)这个拼装规则就是：
ZSH_THEME_GIT_PROMPT_PREFIX="git:("决定左边开头部分。ZSH_THEME_GIT_PROMPT_SUFFIX=") "决定结尾。ZSH_THEME_GIT_PROMPT_DIRTY="* "表示脏仓库时追加的内容。ZSH_THEME_GIT_PROMPT_CLEAN=""表示干净仓库时追加的内容。
你可以直接在自己的主题文件里重定义这组变量。比如我想让前缀简短一点，改成"("；想用+表示脏仓库，就设置ZSH_THEME_GIT_PROMPT_DIRTY="+"。分支名本身由git_prompt_info内部获取，不需要我们自己处理。这个函数很轻量，但它只支持 Git，如果你用 Mercurial 这样的其他版本控制工具，就要考虑 zsh 自带的vcs_info模块，这个我在后面第 4 部分也会展开讲。
2. 不动原文件：把自己的 robbyrussell 版本建出来
2.1 新建主题文件而不是裸改，有几个真实理由
很多初学者会直接vim ~/.oh-my-zsh/themes/robbyrussell.zsh-theme，然后开始改。我强烈不建议这样做，原因不只是“升级会被覆盖”这条看起来很远的事。
第一，主题文件被搞乱了，你很难快速回滚。如果你建了自己的主题文件，.zshrc里把ZSH_THEME改回"robbyrussell"就能得到原始版本，这是一个成本极低的还原方案。第二，独立主题文件方便移植。我的 dotfiles 仓库里只放自定义主题文件，任何一台新机器clone下来，把文件放到custom/themes目录，再设置一下ZSH_THEME，就能还原整个命令行环境，不需要连带处理默认主题目录。第三，升级兼容性更好。oh-my-zsh 官方维护者会更新默认主题，你的自定义主题只依赖git_prompt_info这类公共 API，只要接口没变，它的行为就是稳定的。
2.2 建主题的具体步骤
先确认自定义目录存在：
mkdir -p ~/.oh-my-zsh/custom/themes然后新建一个主题文件。名字随意，但要有意义，我用的名字是myrobby.zsh-theme：
touch ~/.oh-my-zsh/custom/themes/myrobby.zsh-theme接着把默认 robbyrussell 的内容复制进去。你可以在编辑器里手动粘贴，也可以直接用命令行复制：
cp ~/.oh-my-zsh/themes/robbyrussell.zsh-theme ~/.oh-my-zsh/custom/themes/myrobby.zsh-theme然后修改~/.zshrc：
ZSH_THEME="myrobby"保存后执行：
source ~/.zshrc或者直接重开一个终端窗口。如果一切正常，你看到的提示符会和之前几乎一样，因为当前文件里的内容就是原来的副本。
提示：先保证副本能跑通，再开始修改。这个顺序很重要，因为如果你一上来就写新内容，出了问题很难判断是语法错误还是逻辑错误。
2.3 第一个修改：去掉用户名和主机名
我的本机终端场景下，用户名@主机名基本不提供信息，所以我第一个改动的目标就是去掉它们。把自定义主题文件里 PROMPT 改成：
PROMPT='%B%F{blue}%~%f%b $(git_prompt_info) %(!.#.$) '这里我顺手做了两个现代化替换：
%F{blue}和%f是 zsh 原生颜色语法，等价于$fg_bold[blue]和$reset_color。新写法更清晰，也不需要手动包%{...%}，zsh 自己知道这是非打印序列。%B和%b是加粗开关。我用它让路径保持醒目，又不必维护一长串颜色变量。
改完后提示符会变成这样：
~/project/demo (git:main) $干净了很多。这个阶段你已经完成了第一次真正意义上的 robbyrussell 主题修改。后面要做的，就是在自己搭建的模板上继续叠加信息。
3. 按自己的习惯加料：路径、状态、颜色，逐个组合
3.1 目录显示方式：完整路径和短目录名怎么取舍
默认%~显示完整路径。项目结构一旦深，提示符能占掉大半行，比如：
~/work/projects/backend/api/src/utils (git:main) $这时候我第一反应是把路径改短，只显示当前目录名。实现方式是把%~换成%c（或者等价的%.）：
PROMPT='%B%F{blue}%c%f%b $(git_prompt_info) %(!.#.$) '这样不管你在哪一层，提示符都只显示utils。代价也很明显：你会失去路径上下文，在多层目录之间跳转时容易迷路。所以这个方案只适合目录层级浅、常驻在固定项目里的人。
如果你想要更聪明的折中方案，可以用precmd钩子动态计算路径长度再决定显示方式。比如定义一个全局变量，在路径字符数小于某个阈值时显示完整路径，超过阈值就只显示末层目录。我实际的方案就接近这个思路，多数时候提示符很紧凑，需要确认位置时按两下 Tab 或者敲pwd就行，体验平衡得很好。
3.2 右侧提示符：退出码、时间和 Git 信息怎么放
默认 RPROMPT 是空的，右侧空间一直被浪费。如果你经常跑脚本、编译项目，想知道上一条命令是否成功，最直接的用法是把退出码放在右侧：
RPROMPT='%(?..%F{red}exit %?%f)'这行代码用 zsh 条件判断：%(?..)表示“如果上一条命令退出码为 0，不输出内容；否则输出后面的内容”。%?就是退出码，%F{red}...%f让它显示为红色。这样一旦有命令报错，屏幕右侧就会亮起一个红色exit 1之类的提示，效果非常直观。
也有人把 Git 分支放右侧。我不建议这么做，因为主提示符已经放了git_prompt_info，右侧再放一遍就成了重复信息，人眼的注意力会被分散。我自己的习惯是：主提示符保留分支，右侧放退出码和时间。时间用%T就是 HH:MM 格式，想要日期就用%D{%y-%m-%d %H:%M}这种自定义格式。
3.3 动态切换 git 状态颜色，让脏仓库一眼可见
robbyrussell 的默认风格里，整个分支信息使用 reset 之后的默认颜色，所以无论仓库干净还是脏，分支看起来都一样。对“同时在好几个仓库间跳转”的工作流来说，这点不够用。我希望能让干净仓库显示绿色，脏仓库显示红色。
实现思路是定义一个小函数，通过检查 git status 的结果判断仓库状态：
function my_git_color() { if [[ -n "$(git status --porcelain 2>/dev/null)" ]]; then echo "%F{red}" else echo "%F{green}" fi }然后在 PROMPT 里调用它：
PROMPT='$(my_git_color)$(git_prompt_info)%f %(!.#.$) '这里有一个性能问题要提醒：如果直接在 PROMPT 里调用函数，每次提示符渲染都会执行一次git status --porcelain。仓库大的时候，你能明显感觉到按键回显卡顿。更稳妥的做法是把状态计算放到precmd钩子里，命令执行完只算一次，然后把结果存进变量，PROMPT 直接引用变量。比如：
function precmd() { if [[ -n "$(git status --porcelain 2>/dev/null)" ]]; then GIT_COLOR="%F{red}" else GIT_COLOR="%F{green}" fi PROMPT='${GIT_COLOR}$(git_prompt_info)%f %(!.#.$) ' }这样每次命令执行完，状态只需要计算一次，而且渲染提示符时不再触发慢速的 git 检查。
3.4 把虚拟环境、SSH 会话这些环境状态也放进去
经常在多个 Python 虚拟环境之间切换的人，应该体会过“装错环境”的懊恼。把虚拟环境信息显示在提示符里，能有效避免这种问题。我写了个小函数：
function my_virtualenv_indicator() { if [[ -n "$VIRTUAL_ENV" ]]; then echo "%F{yellow}($(basename $VIRTUAL_ENV))%f " fi }然后把它拼到 PROMPT 的最前面：
PROMPT='$(my_virtualenv_indicator)%B%F{blue}%c%f%b $(git_prompt_info) %(!.#.$) '当某个虚拟环境被激活时，提示符会多出黄色括号包裹的环境名。比部分工具提供的“自动显示环境名”更可控，因为它在任何 shell 里都生效，不依赖插件。
SSH 会话也值得处理。你会发现，一旦去掉了主机名显示，SSH 登录远程服务器时就分辨不出自己身在何处，很容易把服务器上的重要目录当成本地目录操作。我的做法是检测$SSH_CONNECTION变量：本地终端为空，SSH 会话里则有值。在 SSH 环境下，把整个提示符前缀改成红色主机名，一眼就能区分。这一层逻辑放进自定义主题文件里，让主题根据环境自动适应，才是真正“改到位”的感觉。
4. 善用 zsh 提示符变量和函数，把自定义能力彻底打开
4.1 precmd 钩子：提示符的“预渲染”入口
很多改动一次不生效，或者状态不能实时刷新，根因都在于对precmd理解不够。zsh 的precmd是“每次显示提示符之前执行的函数”，命令执行完、新提示符出现前，zsh 都会调用它。你在这里给 PROMPT 赋值，就能保证每次提示符都是最新状态。
我举一个实际例子。如果你直接在主题文件最外层写：
PROMPT='$(date +%H:%M) ...'在某些终端里可能得到正确时间，但状态变化时不一定会刷新。而写成：
function precmd() { PROMPT='%F{green}%T%f %B%F{blue}%c%f%b $(git_prompt_info) %(!.#.$) ' }每次命令执行完，PROMPT 都会重新赋值一次，时间、路径、分支全部重新计算。对于状态类信息，这是最稳妥的处理方式。需要注意的是，precmd里不要做太重的计算，否则每执行一条命令都卡一下，体验很差。
4.2 git_prompt_info 和 vcs_info，我到底该用哪个
git_prompt_info的好处是开箱即用，它已经把分支名获取、脏仓库判定这些细节封装好了，robbyrussell 默认主题也依赖它，所以我建议大多数情况下直接用。
但它的局限在于只支持 Git，对 Mercurial 这类工具无能为力。如果你需要更通用的版本控制显示，可以考虑 zsh 自带的vcs_info模块。一个最小可用配置是这样的：
autoload -Uz vcs_info zstyle ':vcs_info:git:*' formats '%b' zstyle ':vcs_info:git:*' actionformats '%b|%a' precmd() { vcs_info PROMPT='${vcs_info_msg_0_} ...' }vcs_info_msg_0_是模块计算后的结果变量，你可以在 PROMPT 里引用它。它比git_prompt_info更“正规”，渲染时机也更可控，代价是需要自己处理颜色和格式。我的建议是：不折腾就没必要换，只有当你明确需要多版本控制支持或者更精细的分支展示时，再迁移过去。
4.3 颜色搭配的边界：低配终端下怎么保底
颜色随便挑是很快的事，但要在本地终端、远程服务器、tmux 会话里都显示正常，就得有些克制。我的经验是主题里最多用三种主色：路径用蓝色，Git 状态用绿色和红色，辅助状态用黄色。这样在深色和浅色背景终端下都稳定。
远程服务器经常不是 256 色环境，如果你在 PROMPT 里写了%F{#RRGGBB}这种真彩色编号，或者用了 256 色编号，低配终端可能显示不出来，甚至直接渲染成一坨乱码。在终端里执行echo $TERM，如果输出是xterm-256color，颜色选择空间会大很多；如果是xterm或者更老的vt100，就只使用八种基础颜色最保险。robbyrussell 默认只依赖绿色、蓝色、红色，其实已经考虑到了这种兼容性问题，这也是它走到哪里都好看的原因之一。
4.4 双宽字符导致提示符错位，怎么处理
很多人喜欢在提示符里加➜、»、★这类符号，看着有个性，但很容易触发终端行列错位问题。原因很简单：zsh 默认假设每个字符占一列宽度，而中文、Emoji、某些图标字体是双宽字符，于是整个行宽计算就错了，表现就是换行位置不对、复制命令时多出空格。
处理方式有两个方向。一个方向是避免用双宽符号，改用 ASCII 字符，比如>、|、#，虽然没那么好看，但绝对稳定。另一个方向是在包含双宽字符的片段外面套上准确的宽度声明，但这依赖具体终端对字符宽度的定义，复杂度高，回报低。我后来放弃了在主题里用花哨符号的念头，发现 robbyrussell 这种纯颜色+括号+文本的极简风格，在维护长期使用的配置时才是最省心的。
5. 改完主题怎么验证：调试手段和踩坑记录
5.1 改了文件不生效，先在加载顺序上找原因
最常见的“改了没反应”，十有八九不是主题文件本身的问题，而是 oh-my-zsh 的加载顺序。完整流程是：打开 shell 时读取.zshrc，然后在.zshrc里调用oh-my-zsh.sh，脚本根据ZSH_THEME变量去加载对应主题文件。主题文件里对 PROMPT 的赋值是最后执行的。
如果你在.zshrc的末尾又给 PROMPT 赋值，或者某个 zsh 插件也往 PROMPT 里追加内容，两者互相覆盖，你的主题改动就看不到了。排查的办法是：先把.zshrc里所有插件相关行临时注释掉，只保留 oh-my-zsh 的基础加载，并且把ZSH_THEME="myrobby"放在最后，再开新终端验证。确认是插件冲突后，再逐个启用插件定位来源。
5.2 颜色蔓延到整个提示符：都怪忘了 reset
早期的自定义主题里，我写过类似这样的代码：
PROMPT='%F{blue}%c $(git_prompt_info) %(!.#.$) '看起来没什么，实际运行起来，git 分支、最后的$全都是蓝色。原因就是我在%F{blue}之后没有用%f重置颜色。别看这问题小，它影响非常大，整个提示符的层次感全没了，看起来像终端渲染出了 bug。
检查原则就一条：每次开启颜色、加粗、背景色，都要在合适的位置用对应的关闭符收尾。表格对照如下：
| 开启 | 关闭 | 作用 |
|---|---|---|
%F{颜色} | %f | 前景色 |
%K{颜色} | %k | 背景色 |
%B | %b | 粗体 |
%U | %u | 下划线 |
%S | %s | 反显 |
养成随手配对写颜色开关的习惯，能省掉大量调试时间。
5.3 用 print -P 快速渲染提示符，不用反复重开终端
调试提示符最痛苦的是每改一次都要重开终端，或者source ~/.zshrc。其实 zsh 提供了一个很直接的验证命令：
print -P '%F{red}红色%f 正常'-P选项会按提示符规则展开转义序列，你可以在命令里输入一小段 PROMPT 内容，马上看到它最终渲染出来的样子。如果想确认 PROMPT 变量里存了什么原始字符串，用：
echo $PROMPT两个命令配合，一个看原始内容，一个看渲染结果，排查效率能高很多。比如某个条件判断不生效，你可以单独把条件片段拿出来用print -P测，很快就能定位问题。
5.4 PROMPT_SUBST 和特殊字符转义，容易踩的暗坑
PROMPT 字符串里的!是个危险角色，它容易被 zsh 当成历史扩展。robbyrussell 默认的%(!.#.$)因为写在条件表达式内部，所以是安全的。但如果你自己写类似PROMPT='history: !'这种内容，轻则显示错乱，重则执行时报错。稳妥的方案是绕开直接使用!，用%系列的转义来完成需求。
$(...)命令替换能不能执行，也依赖一个很容易被忽略的选项：setopt PROMPT_SUBST。oh-my-zsh 默认把它开了，所以$(git_prompt_info)才会被重新计算。如果你离开了 oh-my-zsh，想在裸 zsh 里复刻这个能力，一定要记得在.zshrc里显式加上这一行：
setopt PROMPT_SUBST否则你会发现 PROMPT 里的$(...)被当成纯文本，永远输出不了实际内容。
5.5 不同环境下各看一遍，才算真正改完
主题文件改完，不要只在本机终端确认外观，最好在三个环境里各看一遍：远程服务器、tmux 或 screen 会话、一个 16 色终端模拟器。远程环境常见的坑是缺少图标字体，你的好看符号在那里可能变成方框；tmux 对颜色配置有自己的处理逻辑，颜色值会被重新映射，有时和直接终端里显示不一样；16 色低配终端则会把 256 色颜色强行降级，效果不可控。
如果你把自定义主题同步到多台机器，建议把主题文件放进独立的点文件仓库一起管理。这样任何一台新机器 clone 下来，只要把文件放到custom/themes目录再设置ZSH_THEME，整个终端环境就能复现。我自己折腾完这套 robbyrussell 自定义方案后，就再没被“这台机器提示符怎么不一样”的问题困扰过。
最后再分享一个我个人的操作习惯：每次做较大改动时，先复制一份主题文件作为备份，哪怕只是myrobby.zsh-theme.bak。改到一半发现思路不对，立刻切回去，比在编辑器和终端之间来回折腾稳妥得多。命令行提示符这种东西，一旦用顺了就很依赖，让它按自己的习惯去显示环境状态，这件事带来的效率提升，远比当初花的那几小时调试时间更有价值。
