Spaceship Prompt 的 time 时间段：隐藏时间戳段的配置、格式化与源码原理

• 开发工具

导读

本文聚焦 Spaceship Prompt 内置的time时间段（section）：它用于在命令行提示符中显示当前时间戳，默认隐藏、按需开启。文章将完整讲解如何通过SPACESHIP_TIME_SHOW启用该段、如何切换 12/24 小时制、如何借助 Zsh 日期格式定制SPACESHIP_TIME_FORMAT，并逐一说明全部 6 个配置项的含义与默认值；同时结合sections/time.zsh的源码实现，剖析该段“如何根据配置选择格式串、如何把内容交给渲染管线”的底层调用链，帮助你既会用、又看得懂。

一、time段是什么：默认隐藏的时间戳

time段是 Spaceship Prompt 内置的数十个时间段之一，其职责非常单一——在提示符中显示一条时间戳。在 sections/time.zsh 的头部注释中，它被描述为 “Current time”。

与其他大量默认显示的段（如dir、git）不同，time段默认处于隐藏状态，这一点在 docs/uk/sections/time.md 的文档开头就以警告框（!!! warning "Типово ця секція є прихованою"，即“默认此段是隐藏的”）明确标出。隐藏的原因很直接：终端行首空间宝贵，并非所有用户都需要时刻看到时间；是否展示、以何种格式展示，完全由你决定。

官方内置段注册表（docs/registry/internal.json）对该段的描述是 “The timestamp of the prompt.”（提示符的时间戳），与本段源码、文档的定位完全一致。

二、启用与显示：SPACESHIP_TIME_SHOW

启用time段只需要一行配置。在配置文件中（docs/config/intro.md 介绍了配置文件的标准位置：~/.spaceshiprc.zsh，或~/.config/spaceship.zsh），加入：

SPACESHIP_TIME_SHOW=true

设置后，提示符中就会渲染出一条形如at 14:37:52的时间段。之所以是at前缀，是因为SPACESHIP_TIME_PREFIX的默认值就是at（详见第四节选项表）。

从源码看隐藏与显示的判定

sections/time.zsh中段的入口函数是spaceship_time()，它的第一行就是显隐开关：

spaceship_time() { [[ $SPACESHIP_TIME_SHOW == false ]] && return ... }

也就是说，只要SPACESHIP_TIME_SHOW不等于false（例如被显式设为true），函数就会继续往下执行并输出段内容；保持默认值false时函数直接返回、什么都不渲染。这也是“该段默认隐藏”在源码层面的直接依据。

三、日期与时间格式化：12 小时制与SPACESHIP_TIME_FORMAT

time段支持两种层级的格式化方式：开箱即用的 12 小时制开关，以及完全自定义的 Zsh 日期格式串。

3.1 切换 12 小时制：SPACESHIP_TIME_12HR

如果你习惯 12 小时制（带 am/pm 后缀），只需把SPACESHIP_TIME_12HR设为true：

SPACESHIP_TIME_12HR=true

从 sections/time.zsh 的源码可以看到，这一开关对应的是 Zsh 内置的%r格式（等价于%I:%M:%S %p，例如02:37:52 PM）：

elif [[ $SPACESHIP_TIME_12HR == true ]]; then time_str="%D{%r}" else time_str="%D{%T}" fi

而默认的 24 小时制使用的是%T（等价于%H:%M:%S，例如14:37:52）。

注意：文档正文示例中变量名写的是SPACESHIP_TIME_12HR，这与 sections/time.zsh 第 14 行SPACESHIP_TIME_12HR="${SPACESHIP_TIME_12HR=false}"的源码声明一致，请以SPACESHIP_TIME_12HR为准进行配置。

3.2 完全自定义：SPACESHIP_TIME_FORMAT

如果内置的两种格式都不满足需求，time段几乎支持 Zsh 提示符展开中全部日期/时间格式。你可以通过SPACESHIP_TIME_FORMAT传入任意的%D{...}格式串：

SPACESHIP_TIME_FORMAT='%D{%H:%M:%S.%.}'

这个示例在时分秒之后附加了百分之一秒（%.），渲染效果类似14:37:52.87。常见的可用占位符包括：

3.3 优先级：FORMAT优先于12HR

从 sections/time.zsh 的实现看，三者的选择逻辑是互斥且带优先级的：

if [[ -n $SPACESHIP_TIME_FORMAT ]]; then time_str="${SPACESHIP_TIME_FORMAT}" elif [[ $SPACESHIP_TIME_12HR == true ]]; then time_str="%D{%r}" else time_str="%D{%T}" fi

即：只要SPACESHIP_TIME_FORMAT非空，就直接采用它，完全忽略SPACESHIP_TIME_12HR；仅当格式串为空时，才回退到 12 小时制开关判断；两者都未配置时使用默认的%D{%T}。理解这个优先级，可以避免同时设置两项时产生“为什么没生效”的困惑。

四、全部配置项速查表

以下是time段支持的 6 个配置项，与 docs/uk/sections/time.md 文档中的选项表一一对应，默认值取自 sections/time.zsh 的变量声明：

这些默认值全部通过 Zsh 的${VAR:=default}参数展开形式在 sections/time.zsh 第 10–15 行声明，例如：

SPACESHIP_TIME_SHOW="${SPACESHIP_TIME_SHOW=false}" SPACESHIP_TIME_PREFIX="${SPACESHIP_TIME_PREFIX="at "}" SPACESHIP_TIME_SUFFIX="${SPACESHIP_TIME_SUFFIX="$SPACESHIP_PROMPT_DEFAULT_SUFFIX"}" SPACESHIP_TIME_FORMAT="${SPACESHIP_TIME_FORMAT=}" SPACESHIP_TIME_12HR="${SPACESHIP_TIME_12HR=false}" SPACESHIP_TIME_COLOR="${SPACESHIP_TIME_COLOR="yellow"}"

这意味着：未设置时自动回填默认值，且不会覆盖你已在.zshrc或.spaceshiprc.zsh中显式指定的值。值得注意的是，SPACESHIP_TIME_SUFFIX的默认值直接引用了另一个全局变量SPACESHIP_PROMPT_DEFAULT_SUFFIX，因此修改全局后缀会同步影响time段，除非你显式为它单独赋值。

完整示例：一份可直接运行的time段配置

把下面内容放入配置文件（如~/.spaceshiprc.zsh，详见 docs/config/intro.md），即可得到一个自定义的time段：

# 启用 time 段 SPACESHIP_TIME_SHOW=true # 自定义前缀与颜色 SPACESHIP_TIME_PREFIX="🕐 " SPACESHIP_TIME_COLOR="cyan" # 自定义格式：时:分:秒.百分之一秒 SPACESHIP_TIME_FORMAT='%D{%H:%M:%S.%.}' # 若想用 12 小时制，则改为 true（与 FORMAT 同时设置时 FORMAT 优先生效） # SPACESHIP_TIME_12HR=true

五、源码级原理：time段如何被渲染出来

time段的渲染过程可以拆成“选格式 → 打包 → 渲染”三个环节，整条链路都在仓库源码中清晰可见。

第一步：选择格式串。如第三节所述，spaceship_time()根据SPACESHIP_TIME_FORMAT、SPACESHIP_TIME_12HR的取值，把time_str定为用户格式、%D{%r}或%D{%T}三者之一。%D{...}是 Zsh 的提示符展开语法，表示“按括号内格式展开当前日期时间”，因此最终的时间字符串是在渲染阶段由 Zsh 完成的，段本身只是把格式串原样传递下去。

第二步：打包段元数据。spaceship_time()最终调用spaceship::section，把颜色、前缀、后缀和内容打包成一个元组：

spaceship::section \ --color "$SPACESHIP_TIME_COLOR" \ --prefix "$SPACESHIP_TIME_PREFIX" \ --suffix "$SPACESHIP_TIME_SUFFIX" \ "$time_str"

lib/section.zsh 中的spaceship::section使用zparseopts解析这四个选项，然后把color、prefix、suffix、symbol、content等字段以·|·为分隔符拼接成一个元组字符串输出（lib/section.zsh）。同时，lib/section.zsh还提供了spaceship::section::v3（旧版位置参数风格）与spaceship::section::v4等兼容入口，time段使用的是当前的--color/--prefix/--suffix命名参数风格。

第三步：渲染。spaceship::section::render（lib/section.zsh）负责把元组还原成最终的提示符片段：将颜色包装为%F{$color}、在内容前输出加粗前缀、以%{%B$color%}设置颜色输出$symbol$content、再按SPACESHIP_PROMPT_SUFFIXES_SHOW全局开关决定是否追加后缀。因此time段的实际观感（at 14:37:52）是“前缀 + 着色内容 + 后缀”三段拼接的结果，且前缀/后缀是否显示还受全局的SPACESHIP_PROMPT_PREFIXES_SHOW、SPACESHIP_PROMPT_SUFFIXES_SHOW控制。

从 docs/registry/internal.json 可以看到，time段注册时的描述就是 “The timestamp of the prompt.”，与上述渲染逻辑完全吻合。

与exec_time段的区分

仓库中还内置了一个名字相近的exec_time段（docs/registry/internal.json 中描述为 “The execution time of the last command.”）。两者很容易混淆，但定位完全不同：

• time：当前时刻的时间戳，格式由SPACESHIP_TIME_*系列变量控制，默认隐藏；
• exec_time：上一条命令的执行耗时，默认也不显示（SPACESHIP_EXEC_TIME_SHOW=false），相关默认配置在 sections/exec_time.zsh。

需要显示“现在几点”时配置time，需要显示“刚才那条命令跑了多久”时配置exec_time，二者互补而非替代。

六、常见问题排查

1. 设置了SPACESHIP_TIME_SHOW=true但提示符里看不到时间？先确认配置是否写入了正确的配置文件（~/.spaceshiprc.zsh或~/.config/spaceship.zsh，详见 docs/config/intro.md），并已在新开的 shell 中生效。其次确认没有全局关闭前缀/后缀显示（SPACESHIP_PROMPT_PREFIXES_SHOW、SPACESHIP_PROMPT_SUFFIXES_SHOW被设为false时，at前缀不会渲染）。

2. 同时设置了SPACESHIP_TIME_FORMAT和SPACESHIP_TIME_12HR，为什么是 24 小时制？这是符合预期的：源码中SPACESHIP_TIME_FORMAT优先级最高，只要非空就完全覆盖 12 小时制开关。想用 12 小时制，请移除SPACESHIP_TIME_FORMAT。

3. 想显示毫秒/百分之一秒？在SPACESHIP_TIME_FORMAT中使用%.，如'%D{%H:%M:%S.%.}'，这正是官方文档给出的示例。

4. 自定义格式串不生效？确认格式串以%D{...}形式书写且花括号闭合，并确保SPACESHIP_TIME_FORMAT的值带引号传入，避免 Zsh 将其中的%与花括号解释为其他展开。

七、小结

time段是 Spaceship Prompt 中一个“小而全”的示例：默认隐藏、一行开启、两套快捷格式、一个通吃 Zsh 全部日期格式的自定义入口，外加 6 个命名清晰的配置项。通过本文，你既掌握了从.zshrc/.spaceshiprc.zsh配置它的完整姿势，也理解了它在 sections/time.zsh → lib/section.zsh 中的底层渲染链路。若想进一步了解其它内置段，可查阅 docs/sections/index.md 的内置段清单，或阅读 docs/config/intro.md 了解全局配置方式。

• 开发工具