Spaceship Prompt 配置文件指南从零创建到深度定制你的 Zsh 提示符【免费下载链接】spaceship-prompt✨ Minimalistic, powerful and extremely customizable Zsh prompt项目地址: https://gitcode.com/gh_mirrors/sp/spaceship-prompt本篇技术指南围绕 Spaceship 的配置体系展开如何创建配置文件、配置文件如何被自动加载、如何利用 zsh 语法与SPACESHIP_SECTION_OPTION形式的环境变量逐段定制提示符以及如何通过spaceshipCLI 命令动态增删提示符区块section。读完本文你将掌握从「新建配置文件」到「源码级理解加载机制」的完整技能能够为个人工作流打造一套专属的 Zsh 提示符。配置文件在 Spaceship 启动流程中的角色Spaceship 的个性化定制完全围绕一个配置文件展开。这个文件是普通的.zsh文件Spaceship 在启动时会自动查找并 source加载它。理解这个加载过程是掌握全部配置技巧的前提。默认配置查找路径与顺序在 lib/config.zsh 中Spaceship 定义了一个数组SPACESHIP_CONFIG_PATH按优先级依次探测以下位置SPACESHIP_CONFIG_PATH( $HOME/.spaceshiprc # 用户主目录下的隐藏文件 $HOME/.spaceshiprc.zsh # 主目录下带 .zsh 后缀的版本 ${XDG_CONFIG_HOME:$HOME/.config}/spaceship.zsh # XDG 约定目录 ${XDG_CONFIG_HOME:$HOME/.config}/spaceship/spaceship.zsh # XDG 子目录 ${XDG_CONFIG_DIRS:/etc/xdg}/spaceship.zsh # 系统级 XDG 目录 )加载逻辑如下lib/config.zsh若环境变量SPACESHIP_CONFIG尚未设置则按上述数组顺序逐个检查文件是否存在取第一个存在的文件作为配置文件若找到配置文件则用source加载它加载后调用spaceship::precompile对配置文件做预编译缓存以加快后续启动速度。也就是说如果你同时存在多个候选文件只有最先命中的那个会被加载其余会被忽略。SPACESHIP_CONFIG_PATH本身也可由你在.zshrc中提前覆盖从而完全自定义查找路径。配置文件与 .zshrc 的关系需要强调的是配置文件是在 Spaceship 加载之后才被 source 的它由 spaceship.zsh 通过SPACESHIP_LIBS列表中的lib/config.zsh加载。因此配置文件里可以直接调用spaceship命令和spaceship::函数这是它与.zshrc的主要区别之一.zshrc负责「加载 Spaceship 本体」配置文件负责「定制 Spaceship 行为」。第一步创建你的配置文件根据 docs/uk/config/intro.md 的说明创建配置文件有两种推荐方式。方式一主目录下的隐藏文件最简单touch ~/.spaceshiprc.zsh方式二遵循 XDG 目录规范适合 dotfiles 管理mkdir -p ~/.config touch ~/.config/spaceship.zsh也可以把配置文件放进~/.config/spaceship/子目录mkdir -p ~/.config/spaceship touch ~/.config/spaceship/spaceship.zsh对照前文的SPACESHIP_CONFIG_PATH可以看到~/.config/spaceship.zsh与~/.config/spaceship/spaceship.zsh都是默认会被自动识别的路径。文件创建后新开一个终端会话即自动生效无需额外注册。第二步用 zsh 语法定制提示符配置文件本质上是一个.zsh文件因此你可以使用完整的 zsh 语法循环、条件判断、自定义函数甚至通过source引入其他 zsh 文件例如把不同项目的配置拆分成多个文件再统一加载。一切由你掌控。选项命名约定SPACESHIP__Spaceship 的提示符由若干**区块section组成每个区块又由前缀prefix、符号symbol、内容content、后缀suffix**构成。每个可配置项都是一个环境变量命名遵循统一签名SPACESHIP_SECTION_OPTION例如# SPACESHIP_SECTION_OPTION SPACESHIP_PACKAGE_PREFIXvia· SPACESHIP_PACKAGE_SUFFIX SPACESHIP_PACKAGE_COLORgreen其中PACKAGE是区块名PREFIX、SUFFIX、COLOR分别是「前缀、后缀、颜色」选项。区块名使用spaceship_前缀如spaceship_package注册变量名使用SPACESHIP_前缀从而避免与全局环境变量冲突参见 docs/api/environment.md。官方示例配置逐行解析下面是 docs/uk/config/intro.md 给出的示例配置文件我们结合源码逐行深入# 显示时间 SPACESHIP_TIME_SHOWtrue # 始终显示用户名 SPACESHIP_USER_SHOWalways # 在 git 仓库内不截断路径 SPACESHIP_DIR_TRUNC_REPOfalse # 添加外部 Ember 区块 spaceship add ember # 在 char 区块之前添加 vi-mode 区块 spaceship add --before char vi_modeSPACESHIP_TIME_SHOWtrue默认情况下时间区块是关闭的见 sections/time.zsh 中SPACESHIP_TIME_SHOW${SPACESHIP_TIME_SHOWfalse}设为true即可启用。还可以配套使用SPACESHIP_TIME_FORMAT自定义格式、SPACESHIP_TIME_12HR12 小时制、SPACESHIP_TIME_COLOR默认黄色等选项。SPACESHIP_USER_SHOWalways用户区块默认取值是true语义为「本地按需显示、远程始终显示」。源码sections/user.zsh支持四档取值false从不显示、always总是显示、true本地按需/远程显示、needed仅在需要时显示。root 用户默认用红色SPACESHIP_USER_COLOR_ROOT高亮普通用户为黄色。SPACESHIP_DIR_TRUNC_REPOfalse目录区块默认会把路径截断为最后 3 级SPACESHIP_DIR_TRUNC3并且在 git 仓库内把仓库根目录视为顶层SPACESHIP_DIR_TRUNC_REPOtrue见 sections/dir.zsh。设为false后仓库内路径将不再以仓库根为截断基准。spaceship add ember/spaceship add --before char vi_mode调用 Spaceship CLI 把外部区块插入提示符顺序详见下文。在 .zshrc 中加载配置的补充说明示例中的spaceship add调用需要写入.zshrc在 Spaceship 加载之后执行或配置文件本身。如果你在.zshrc中管理区块顺序请确保这些命令出现在sourceSpaceship 主题之后。第三步改变配置文件的位置如果你习惯把配置文件托管在 dotfiles 仓库里可以通过环境变量指定任意路径。官方文档 docs/uk/config/intro.md 中的写法是export SPACESHIP_CONFIG$HOME/.dotfiles/path/to/spaceship.zsh需要说明的是实际起作用的变量是SPACESHIP_CONFIG在 lib/config.zsh 中正是用它来判断是否跳过默认路径搜索并直接加载。部分文档版本包括 docs/api/environment.md会以SPACESHIP_CONFIG_FILE命名该变量但源码逻辑以SPACESHIP_CONFIG为准——请在.zshrc中设置SPACESHIP_CONFIG并将这行代码放在加载 Spaceship 之前。设置后Spaceship 会直接加载该路径下的文件若该文件不存在SPACESHIP_CONFIG保持为空Spaceship 退回默认路径搜索。深入用 spaceship CLI 管理区块顺序提示符中区块的执行顺序由SPACESHIP_PROMPT_ORDER数组决定默认定义在 spaceship.zsh。与其手写整个数组更推荐使用spaceshipCLI 动态增删# 从提示符中移除 git 区块 spaceship remove git # 把 git 区块加回提示符 spaceship add gitCLI 在 lib/cli.zsh 中实现add子命令支持三个定位参数--before section/-B在指定区块之前插入默认在line_sep之前--after section/-A在指定区块之后插入--order name/-O指定要修改的顺序数组默认prompt即SPACESHIP_PROMPT_ORDER。spaceship remove则从顺序数组中过滤掉指定区块。这两个命令都会改写SPACESHIP_PROMPT_ORDER并立即生效因此非常适合写进配置文件中按需组合区块。另外spaceshipCLI 还提供edit用$EDITOR打开配置文件并重新加载、print打印当前提示符支持-P prompt|rprompt|ps2、version等子命令可用于日常调试。常用提示符级选项速查除区块级选项外Spaceship 还有一组影响全局的选项默认值定义于 spaceship.zsh详细说明见 docs/config/prompt.md变量默认值含义SPACESHIP_PROMPT_ASYNCtrue是否异步渲染提示符SPACESHIP_PROMPT_ADD_NEWLINEtrue每行提示符前是否追加空行SPACESHIP_PROMPT_SEPARATE_LINEtrue提示符是否跨两行显示SPACESHIP_PROMPT_FIRST_PREFIX_SHOWfalse是否显示第一个区块的前缀SPACESHIP_RPROMPT_FIRST_PREFIX_SHOWfalse是否显示右提示符第一个区块的前缀SPACESHIP_PROMPT_PREFIXES_SHOWtrue是否显示区块前缀SPACESHIP_PROMPT_SUFFIXES_SHOWtrue是否显示区块后缀SPACESHIP_PROMPT_DEFAULT_PREFIXvia区块默认前缀SPACESHIP_PROMPT_DEFAULT_SUFFIX区块默认后缀例如关闭空行、关闭前缀显示、启用首个区块前缀的写法SPACESHIP_PROMPT_ADD_NEWLINEfalse SPACESHIP_PROMPT_PREFIXES_SHOWfalse SPACESHIP_PROMPT_FIRST_PREFIX_SHOWtrue右提示符rprompt可通过SPACESHIP_RPROMPT_ORDER数组配置默认是空数组spaceship.zsh。验证与调试验证配置是否被加载执行echo $SPACESHIP_CONFIG若输出的是你创建的配置文件路径说明加载成功若为空说明没有找到任何候选配置文件。查看当前版本spaceship version输出SPACESHIP_VERSION当前仓库为4.22.5见 spaceship.zsh。快速编辑配置spaceship edit会用$EDITOR打开SPACESHIP_CONFIG指向的文件并在保存后重新 source见 lib/cli.zsh。打印提示符spaceship print可直接在终端输出渲染结果方便确认区块增减是否生效。小结Spaceship 的定制流程可以概括为三步创建配置文件自动加载→ 用SPACESHIP_SECTION_OPTION环境变量逐区块定制 → 用spaceship add/remove编排区块顺序。配置文件路径的查找优先级由 lib/config.zsh 中的SPACESHIP_CONFIG_PATH决定也可通过SPACESHIP_CONFIG完全接管。至此你可以把时间、用户、目录、语言运行时乃至外部区块自由组合构建出贴合个人工作流的极简而强大的 Zsh 提示符。更多可用选项请继续查阅 docs/config/prompt.md 及各区块文档docs/sections/index.md外部区块的安装方式见 docs/config/loading-sections.md。【免费下载链接】spaceship-prompt✨ Minimalistic, powerful and extremely customizable Zsh prompt项目地址: https://gitcode.com/gh_mirrors/sp/spaceship-prompt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Spaceship Prompt 配置文件指南：从零创建到深度定制你的 Zsh 提示符
Spaceship Prompt 配置文件指南从零创建到深度定制你的 Zsh 提示符【免费下载链接】spaceship-prompt✨ Minimalistic, powerful and extremely customizable Zsh prompt项目地址: https://gitcode.com/gh_mirrors/sp/spaceship-prompt本篇技术指南围绕 Spaceship 的配置体系展开如何创建配置文件、配置文件如何被自动加载、如何利用 zsh 语法与SPACESHIP_SECTION_OPTION形式的环境变量逐段定制提示符以及如何通过spaceshipCLI 命令动态增删提示符区块section。读完本文你将掌握从「新建配置文件」到「源码级理解加载机制」的完整技能能够为个人工作流打造一套专属的 Zsh 提示符。配置文件在 Spaceship 启动流程中的角色Spaceship 的个性化定制完全围绕一个配置文件展开。这个文件是普通的.zsh文件Spaceship 在启动时会自动查找并 source加载它。理解这个加载过程是掌握全部配置技巧的前提。默认配置查找路径与顺序在 lib/config.zsh 中Spaceship 定义了一个数组SPACESHIP_CONFIG_PATH按优先级依次探测以下位置SPACESHIP_CONFIG_PATH( $HOME/.spaceshiprc # 用户主目录下的隐藏文件 $HOME/.spaceshiprc.zsh # 主目录下带 .zsh 后缀的版本 ${XDG_CONFIG_HOME:$HOME/.config}/spaceship.zsh # XDG 约定目录 ${XDG_CONFIG_HOME:$HOME/.config}/spaceship/spaceship.zsh # XDG 子目录 ${XDG_CONFIG_DIRS:/etc/xdg}/spaceship.zsh # 系统级 XDG 目录 )加载逻辑如下lib/config.zsh若环境变量SPACESHIP_CONFIG尚未设置则按上述数组顺序逐个检查文件是否存在取第一个存在的文件作为配置文件若找到配置文件则用source加载它加载后调用spaceship::precompile对配置文件做预编译缓存以加快后续启动速度。也就是说如果你同时存在多个候选文件只有最先命中的那个会被加载其余会被忽略。SPACESHIP_CONFIG_PATH本身也可由你在.zshrc中提前覆盖从而完全自定义查找路径。配置文件与 .zshrc 的关系需要强调的是配置文件是在 Spaceship 加载之后才被 source 的它由 spaceship.zsh 通过SPACESHIP_LIBS列表中的lib/config.zsh加载。因此配置文件里可以直接调用spaceship命令和spaceship::函数这是它与.zshrc的主要区别之一.zshrc负责「加载 Spaceship 本体」配置文件负责「定制 Spaceship 行为」。第一步创建你的配置文件根据 docs/uk/config/intro.md 的说明创建配置文件有两种推荐方式。方式一主目录下的隐藏文件最简单touch ~/.spaceshiprc.zsh方式二遵循 XDG 目录规范适合 dotfiles 管理mkdir -p ~/.config touch ~/.config/spaceship.zsh也可以把配置文件放进~/.config/spaceship/子目录mkdir -p ~/.config/spaceship touch ~/.config/spaceship/spaceship.zsh对照前文的SPACESHIP_CONFIG_PATH可以看到~/.config/spaceship.zsh与~/.config/spaceship/spaceship.zsh都是默认会被自动识别的路径。文件创建后新开一个终端会话即自动生效无需额外注册。第二步用 zsh 语法定制提示符配置文件本质上是一个.zsh文件因此你可以使用完整的 zsh 语法循环、条件判断、自定义函数甚至通过source引入其他 zsh 文件例如把不同项目的配置拆分成多个文件再统一加载。一切由你掌控。选项命名约定SPACESHIP__Spaceship 的提示符由若干**区块section组成每个区块又由前缀prefix、符号symbol、内容content、后缀suffix**构成。每个可配置项都是一个环境变量命名遵循统一签名SPACESHIP_SECTION_OPTION例如# SPACESHIP_SECTION_OPTION SPACESHIP_PACKAGE_PREFIXvia· SPACESHIP_PACKAGE_SUFFIX SPACESHIP_PACKAGE_COLORgreen其中PACKAGE是区块名PREFIX、SUFFIX、COLOR分别是「前缀、后缀、颜色」选项。区块名使用spaceship_前缀如spaceship_package注册变量名使用SPACESHIP_前缀从而避免与全局环境变量冲突参见 docs/api/environment.md。官方示例配置逐行解析下面是 docs/uk/config/intro.md 给出的示例配置文件我们结合源码逐行深入# 显示时间 SPACESHIP_TIME_SHOWtrue # 始终显示用户名 SPACESHIP_USER_SHOWalways # 在 git 仓库内不截断路径 SPACESHIP_DIR_TRUNC_REPOfalse # 添加外部 Ember 区块 spaceship add ember # 在 char 区块之前添加 vi-mode 区块 spaceship add --before char vi_modeSPACESHIP_TIME_SHOWtrue默认情况下时间区块是关闭的见 sections/time.zsh 中SPACESHIP_TIME_SHOW${SPACESHIP_TIME_SHOWfalse}设为true即可启用。还可以配套使用SPACESHIP_TIME_FORMAT自定义格式、SPACESHIP_TIME_12HR12 小时制、SPACESHIP_TIME_COLOR默认黄色等选项。SPACESHIP_USER_SHOWalways用户区块默认取值是true语义为「本地按需显示、远程始终显示」。源码sections/user.zsh支持四档取值false从不显示、always总是显示、true本地按需/远程显示、needed仅在需要时显示。root 用户默认用红色SPACESHIP_USER_COLOR_ROOT高亮普通用户为黄色。SPACESHIP_DIR_TRUNC_REPOfalse目录区块默认会把路径截断为最后 3 级SPACESHIP_DIR_TRUNC3并且在 git 仓库内把仓库根目录视为顶层SPACESHIP_DIR_TRUNC_REPOtrue见 sections/dir.zsh。设为false后仓库内路径将不再以仓库根为截断基准。spaceship add ember/spaceship add --before char vi_mode调用 Spaceship CLI 把外部区块插入提示符顺序详见下文。在 .zshrc 中加载配置的补充说明示例中的spaceship add调用需要写入.zshrc在 Spaceship 加载之后执行或配置文件本身。如果你在.zshrc中管理区块顺序请确保这些命令出现在sourceSpaceship 主题之后。第三步改变配置文件的位置如果你习惯把配置文件托管在 dotfiles 仓库里可以通过环境变量指定任意路径。官方文档 docs/uk/config/intro.md 中的写法是export SPACESHIP_CONFIG$HOME/.dotfiles/path/to/spaceship.zsh需要说明的是实际起作用的变量是SPACESHIP_CONFIG在 lib/config.zsh 中正是用它来判断是否跳过默认路径搜索并直接加载。部分文档版本包括 docs/api/environment.md会以SPACESHIP_CONFIG_FILE命名该变量但源码逻辑以SPACESHIP_CONFIG为准——请在.zshrc中设置SPACESHIP_CONFIG并将这行代码放在加载 Spaceship 之前。设置后Spaceship 会直接加载该路径下的文件若该文件不存在SPACESHIP_CONFIG保持为空Spaceship 退回默认路径搜索。深入用 spaceship CLI 管理区块顺序提示符中区块的执行顺序由SPACESHIP_PROMPT_ORDER数组决定默认定义在 spaceship.zsh。与其手写整个数组更推荐使用spaceshipCLI 动态增删# 从提示符中移除 git 区块 spaceship remove git # 把 git 区块加回提示符 spaceship add gitCLI 在 lib/cli.zsh 中实现add子命令支持三个定位参数--before section/-B在指定区块之前插入默认在line_sep之前--after section/-A在指定区块之后插入--order name/-O指定要修改的顺序数组默认prompt即SPACESHIP_PROMPT_ORDER。spaceship remove则从顺序数组中过滤掉指定区块。这两个命令都会改写SPACESHIP_PROMPT_ORDER并立即生效因此非常适合写进配置文件中按需组合区块。另外spaceshipCLI 还提供edit用$EDITOR打开配置文件并重新加载、print打印当前提示符支持-P prompt|rprompt|ps2、version等子命令可用于日常调试。常用提示符级选项速查除区块级选项外Spaceship 还有一组影响全局的选项默认值定义于 spaceship.zsh详细说明见 docs/config/prompt.md变量默认值含义SPACESHIP_PROMPT_ASYNCtrue是否异步渲染提示符SPACESHIP_PROMPT_ADD_NEWLINEtrue每行提示符前是否追加空行SPACESHIP_PROMPT_SEPARATE_LINEtrue提示符是否跨两行显示SPACESHIP_PROMPT_FIRST_PREFIX_SHOWfalse是否显示第一个区块的前缀SPACESHIP_RPROMPT_FIRST_PREFIX_SHOWfalse是否显示右提示符第一个区块的前缀SPACESHIP_PROMPT_PREFIXES_SHOWtrue是否显示区块前缀SPACESHIP_PROMPT_SUFFIXES_SHOWtrue是否显示区块后缀SPACESHIP_PROMPT_DEFAULT_PREFIXvia区块默认前缀SPACESHIP_PROMPT_DEFAULT_SUFFIX区块默认后缀例如关闭空行、关闭前缀显示、启用首个区块前缀的写法SPACESHIP_PROMPT_ADD_NEWLINEfalse SPACESHIP_PROMPT_PREFIXES_SHOWfalse SPACESHIP_PROMPT_FIRST_PREFIX_SHOWtrue右提示符rprompt可通过SPACESHIP_RPROMPT_ORDER数组配置默认是空数组spaceship.zsh。验证与调试验证配置是否被加载执行echo $SPACESHIP_CONFIG若输出的是你创建的配置文件路径说明加载成功若为空说明没有找到任何候选配置文件。查看当前版本spaceship version输出SPACESHIP_VERSION当前仓库为4.22.5见 spaceship.zsh。快速编辑配置spaceship edit会用$EDITOR打开SPACESHIP_CONFIG指向的文件并在保存后重新 source见 lib/cli.zsh。打印提示符spaceship print可直接在终端输出渲染结果方便确认区块增减是否生效。小结Spaceship 的定制流程可以概括为三步创建配置文件自动加载→ 用SPACESHIP_SECTION_OPTION环境变量逐区块定制 → 用spaceship add/remove编排区块顺序。配置文件路径的查找优先级由 lib/config.zsh 中的SPACESHIP_CONFIG_PATH决定也可通过SPACESHIP_CONFIG完全接管。至此你可以把时间、用户、目录、语言运行时乃至外部区块自由组合构建出贴合个人工作流的极简而强大的 Zsh 提示符。更多可用选项请继续查阅 docs/config/prompt.md 及各区块文档docs/sections/index.md外部区块的安装方式见 docs/config/loading-sections.md。【免费下载链接】spaceship-prompt✨ Minimalistic, powerful and extremely customizable Zsh prompt项目地址: https://gitcode.com/gh_mirrors/sp/spaceship-prompt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考