第 1 章：项目全貌 —— Oh My Zsh 的本质是启动编排器¶
这一章先建立地图：Oh My Zsh 不是一个新的 shell，也不是单纯的主题市场，而是把 zsh 原生扩展点组织成了一套约定。
1.1 一句话定义¶
Oh My Zsh 是一个以 source 为核心的 zsh 运行时集合。用户在 ~/.zshrc 中声明少量变量，然后把控制权交给 $ZSH/oh-my-zsh.sh；后者完成路径、补全、更新、库、插件、custom 和主题的编排。
因此它的“框架能力”主要来自三种机制：
- 命名约定：
plugins/foo/foo.plugin.zsh、plugins/foo/_foo、themes/foo.zsh-theme。 - 加载顺序：内置
lib先于插件，插件先于 custom，theme 最后。 - 可覆盖查找：优先从
$ZSH_CUSTOM找同名文件，再退回$ZSH。
这三个机制足以让用户不用修改核心文件，就能替换绝大多数行为。
1.2 目录职责不是对称的¶
flowchart TB
subgraph Runtime[启动时会被编排]
L[lib/*.zsh<br/>默认 shell 能力]
P[plugins/*<br/>按需功能]
C[custom/*.zsh<br/>用户覆盖]
T[themes/*.zsh-theme<br/>最终 prompt]
end
S[oh-my-zsh.sh] --> L
S --> P
S --> C
S --> T
F[fpath] -.提供 autoload 查找.-> P
F -.提供补全查找.-> T
K[cache/] -.持久化状态.-> S| 目录 | 载入方式 | 典型内容 | 关键风险 |
|---|---|---|---|
lib/ |
启动时遍历并 source |
setopt、alias、hook、公共函数 |
每个模块都影响所有用户 |
plugins/ |
用户列入 plugins=(...) 后加载 |
工具别名、环境变量、补全、函数 | 插件多会变慢或产生命令冲突 |
themes/ |
由 ZSH_THEME 选择后 source |
PROMPT、RPROMPT、prompt helper |
主题依赖公共函数和终端字体 |
custom/ |
内置内容后加载 | 用户函数、别名、同名插件/主题 | 覆盖强大，也容易隐藏真实来源 |
templates/ |
安装时复制，不是运行时模块 | .zshrc 初始模板 |
模板更新不会自动回写用户配置 |
tools/ |
安装/更新/诊断时显式调用 | install.sh、upgrade.sh |
直接执行，必须注意网络和权限 |
1.3 为什么没有“注册表”¶
很多框架会有一个中央 manifest，列出所有插件和依赖。Oh My Zsh 更接近“文件系统即注册表”：
plugins数组给出主动插件的名字；- 文件名决定是否被识别为插件或补全；
fpath决定 zsh 后续能否 autoload 到函数；- 主题名直接映射到某个
.zsh-theme文件。
这让贡献者只需添加目录和文件即可扩展，代价是依赖关系不会被机器完整表达。一个插件可能依赖某个外部命令、某个 lib 函数或某个 zsh 版本，但这些依赖主要靠 README、运行时判断和社区约定维护。
1.4 四种“执行”不要混淆¶
阅读源码时最容易把下面四件事混为一谈：
source¶
source 在当前 shell 执行文件，变量、函数、alias 和 option 会留下来。oh-my-zsh.sh、lib、插件和主题都属于这一类。
autoload¶
autoload -U foo 只把函数标记为可延迟加载，函数体通常从 fpath 中的文件取得。补全函数 _docker、_git 等主要靠这条路径。
compinit¶
compinit 是一次性的补全初始化过程，会根据 fpath 发现补全函数并生成 zcompdump。所以插件目录必须在 compinit 之前进入 fpath。
hook¶
precmd、preexec 等 hook 不会立刻执行主体逻辑，而是在 shell 生命周期的指定时机触发。终端标题、异步 Git prompt 和后台更新都依赖这种延迟。
1.5 主要设计取舍¶
优点：
- 不需要 daemon、数据库或编译器；
- 用户可以直接阅读和覆盖 shell 脚本；
- 插件贡献门槛低，git clone 后即可工作；
fpath和 autoload 让补全可按需加载；- 内置内容与用户内容通过目录分离。
代价：
source是全局副作用，加载顺序就是隐形依赖；- alias/function 同名冲突需要用户自己理解覆盖关系；
- shell 启动性能会被每个模块的外部命令调用拖慢；
- 插件没有统一的依赖、版本和沙箱模型；
- 更新实际上是 Git 工作树操作，不是原子包管理。
1.6 从哪里开始追源码¶
推荐沿着下面四个入口跳转：
templates/zshrc.zsh-template：看用户能配置什么，以及哪些设置必须发生在 source 之前。oh-my-zsh.sh：看启动顺序和覆盖规则。lib/git.zsh：看公共函数如何被主题和插件消费。- 任意一个插件/主题：把抽象约定落到具体文件。
下一章不再按目录讲，而是严格按执行时间线，解释这些入口如何串起来。