企业官网建设流程全解析

• 开发工具

time是 Spaceship 提示符（Zsh prompt）中负责显示当前时间戳的内置 Section，默认隐藏，需要显式开启。本文以官方文档 docs/sections/time.md 为核心骨架，结合 sections/time.zsh 与 lib/section.zsh 的源码实现，完整讲解该 Section 的启用方式、时间格式定制、全部配置项，以及它在整个 prompt 渲染流水线中的工作位置。读完本文，你将能够独立配置出符合需求的 12 小时制、带毫秒或任意 strftime 格式的时间戳，并理解其底层渲染原理。

Section 概述与默认行为

timeSection 的作用非常单一：在 prompt 上显示命令提示符出现时的时间戳。它可以用于：

• 追踪命令执行的历史时刻，便于复盘操作过程；
• 区分长时间终端会话中不同时段的操作；
• 配合exec_time（命令执行时长）Section，精确掌握每条命令发生的时间点。

需要注意，该 Section 默认是隐藏的（SPACESHIP_TIME_SHOW默认为false），源码 sections/time.zsh 中明确声明：

SPACESHIP_TIME_SHOW="${SPACESHIP_TIME_SHOW=false}"

而函数体的第一行守卫逻辑也与此对应（sections/time.zsh）：

[[ $SPACESHIP_TIME_SHOW == false ]] && return

也就是说，只要SPACESHIP_TIME_SHOW不是true，该 Section 直接返回，不产生任何渲染开销。

启用 time Section

在~/.zshrc中加入如下配置即可显示时间戳：

SPACESHIP_TIME_SHOW=true

开启后，提示符最左侧（time位于默认 prompt 顺序的首位）会出现类似at 21:14:33的内容，其中at是该 Section 的默认前缀（prefix），21:14:33是默认的时间内容。

关于配置文件的更多说明，可参考 docs/config/intro.md 中创建配置文件的部分。

时间格式定制

12 小时制（am/pm）

如果你习惯美式 12 小时制，只需开启SPACESHIP_TIME_12HR：

SPACESHIP_TIME_12HR=true

开启后显示效果类似at 09:14:33 PM。源码中的实现逻辑非常直观（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

可以看到，12 小时制实际使用的是 Zsh 的%r格式符，而默认 24 小时制使用的是%T。

注意文档勘误：docs/sections/time.md 正文中该变量写作SPACESHIP_TIME_12HOUR，但代码示例与 sections/time.zsh 源码中实际的变量名均为SPACESHIP_TIME_12HR。使用时请以SPACESHIP_TIME_12HR为准。

自定义任意格式（SPACESHIP_TIME_FORMAT）

通过SPACESHIP_TIME_FORMAT可以使用 Zsh 支持的任何日期时间格式。它采用%D{...}语法包裹，内部为 strftime 风格格式符。官方文档给出的示例为毫秒级时间戳：

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

常见格式符速查（均为 Zsh prompt expansion 标准支持）：

因此你可以组合出诸如%D{%F %T}（2026-09-20 21:14:33）这类带日期的完整时间戳。格式符的具体定义对应 Zsh 官方文档 "Prompt Expansion" 一章中的 Date and time 小节。

优先级规则：从源码if / elif / else分支可见，SPACESHIP_TIME_FORMAT的优先级最高——只要非空即采用它；其次才是SPACESHIP_TIME_12HR；两者都未设置时退回默认的%D{%T}。

选项总览

以上默认值均可在源码 sections/time.zsh 中得到验证。几个值得注意的细节：

• 文档表格中的at·是文档排版中用于可视化空格的写法，源码中的真实默认值是"at "（at加一个空格），见 sections/time.zsh。
• SPACESHIP_TIME_SUFFIX默认继承 prompt 级全局变量SPACESHIP_PROMPT_DEFAULT_SUFFIX，其默认值为单个空格 ，定义见 docs/config/prompt.md 的 Prompt-level options 表格。
• 颜色支持 Zsh 基本颜色名（如yellow、red、green）或 256 色颜色码。

源码级原理：从配置到渲染

1. 时间字符串的构造

spaceship_time()函数（sections/time.zsh）只做两件事：根据上文提到的优先级分支构造time_str，然后调用统一的 Section 打包函数：

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

注意：time不携带 symbol（图标），内容$time_str本身就是时间字符串。由于%D{...}属于 Zsh prompt 扩展语法，实际的时间展开发生在 zsh 渲染 prompt 时，而不是函数调用时——这也是该 Section 轻量、无需外部命令的原因。

2. Section 的打包与渲染

spaceship::section（lib/section.zsh）将color / prefix / suffix / symbol / content打包成一个用·|·分隔的元组字符串；spaceship::section::render（lib/section.zsh）再将其还原并拼装为带 ANSI 转义的真实渲染串：

• 颜色通过%F{$color}包裹（lib/section.zsh）；
• 前缀与后缀在渲染时以粗体输出，并受全局开关SPACESHIP_PROMPT_PREFIXES_SHOW/SPACESHIP_PROMPT_SUFFIXES_SHOW控制（lib/section.zsh）；
• 若 content 与 symbol 均为空，则整个 Section 不渲染（lib/section.zsh）。

3. 在 prompt 顺序中的位置

time位于默认SPACESHIP_PROMPT_ORDER的第一位（见 docs/config/prompt.md 中的默认顺序列表），因此它默认会显示在 prompt 的最左侧。渲染时，lib/core.zsh 的spaceship::core::compose_order按顺序遍历 prompt order，从缓存中取出每个 Section 的渲染结果并拼接成最终 prompt。

两个与位置相关的全局行为值得留意：

• SPACESHIP_PROMPT_FIRST_PREFIX_SHOW默认为false，即第一个 Section 的前缀会被隐藏。因此开启time后，如果它是 prompt 第一项，at前缀可能不会显示。若希望显示，可设置SPACESHIP_PROMPT_FIRST_PREFIX_SHOW=true；
• 若希望时间显示在右侧 prompt，可将time加入SPACESHIP_RPROMPT_ORDER（默认空数组），例如：

SPACESHIP_RPROMPT_ORDER=(time)

完整配置示例

下面是一份可直接放入~/.zshrc的完整示例，涵盖启用、12 小时制与自定义格式三种场景：

# 场景一：最简启用（24 小时制，黄色） SPACESHIP_TIME_SHOW=true # 场景二：12 小时制 SPACESHIP_TIME_SHOW=true SPACESHIP_TIME_12HR=true # 场景三：自定义格式（带日期与毫秒），并覆盖颜色与前缀 SPACESHIP_TIME_SHOW=true SPACESHIP_TIME_FORMAT='%D{%F %T.%.}' SPACESHIP_TIME_COLOR="cyan" SPACESHIP_TIME_PREFIX="now "

将变量写入~/.zshrc后，重新加载配置（source ~/.zshrc）或新开终端窗口即可看到效果。若你通过spaceship add time命令将time加入 prompt 顺序（命令用法见 docs/config/loading-sections.md），同样需要先设置SPACESHIP_TIME_SHOW=true才会实际显示。

常见问题

Q：设置了SPACESHIP_TIME_SHOW=true但没有看到时间？检查SPACESHIP_PROMPT_FIRST_PREFIX_SHOW与顺序因素外，还需确认time确实存在于SPACESHIP_PROMPT_ORDER中（默认存在）。若时间显示在行首但没有前缀，属于上文提到的“首个 Section 前缀默认隐藏”行为。

Q：SPACESHIP_TIME_12HOUR设置无效？正确变量名是SPACESHIP_TIME_12HR。文档正文中的SPACESHIP_TIME_12HOUR为笔误，请以源码与本文为准。

Q：为什么没有毫秒？默认格式%D{%T}不含毫秒，需要毫秒需显式设置SPACESHIP_TIME_FORMAT='%D{%H:%M:%S.%.}'。

Q：能否只显示日期不显示时间？可以。SPACESHIP_TIME_FORMAT='%D{%F}'即可输出2026-09-20格式的日期。

如需了解 Section 机制更通用的设计（prefix/suffix/color 的通用约定、自定义 Section 的开发方法），可进一步阅读 docs/config/prompt.md 与 docs/advanced/creating-section.md。

• 开发工具