macos 上的 zsh 启动问题记录

起因

Cursor 更新重启后，内置终端变得异常缓慢，底部还弹出一堆 warning：

• Shell integration: Basic（降级为基础模式）
• The following extensions want to relaunch the terminal

直觉告诉我这是 IDE 的问题，但实际上，IDE 只是暴露了早就存在的问题。

诊断

zsh 有一个内置的性能分析工具 zprof，一行命令就能看到启动耗时分布：

zsh -c 'zmodload zsh/zprof; source ~/.zshrc; zprof'

结果让人吃惊：

函数	耗时	占比	调用次数
nvm_auto	427ms	50.8%	2
nvm	344ms	41.0%	4
compinit	336ms	40.0%	3
compdef	96ms	11.4%	1610

总启动时间 1.08 秒。一个空终端启动要 1 秒，这已经到了肉眼可感的程度。

三个病灶

1. nvm 被加载了三次

# .zshrc 中的三处 nvm 加载：

# 1) oh-my-zsh nvm 插件加载
plugins=(git nvm)

# 2) 手动 source（与插件重复）
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 3) 自定义 load-nvmrc 启动时调用
load-nvmrc  # 终端启动时触发

nvm 的 nvm.sh 大约 5000 行，每次 source 都要解析一遍。三次就是近 500ms。

2. compinit 被调用了三次

# 1) OPENSPEC 块
compinit

# 2) oh-my-zsh 内部
# (在 source $ZSH/oh-my-zsh.sh 时自动调用)

# 3) Docker Desktop 自动追加的
compinit

compinit 会扫描所有 fpath 目录、解析补全定义文件、重建缓存。调用一次约 110ms，三次就是 330ms。而且每次都会触发 compdef 重新注册所有补全函数——1610 次调用就是这么来的。

3. zstyle 配置放错了位置

# 错误：放在 source oh-my-zsh 之后
source $ZSH/oh-my-zsh.sh

zstyle ':omz:plugins:nvm' autoload yes  # 太晚了，插件已经加载完了

oh-my-zsh 在 source 时就会读取 zstyle 配置来决定插件的行为。放在后面等于没设置，插件使用了默认行为。

修复

修复思路很简单：去重 + 归位 + 懒加载。

# 所有 fpath 在 source oh-my-zsh 之前声明
fpath=("/Users/qs/.oh-my-zsh/custom/completions" $fpath)
fpath=(/Users/qs/.docker/completions $fpath)

# zstyle 配置也在 source 之前
zstyle ':omz:plugins:nvm' lazy yes         # 延迟到首次使用时加载
zstyle ':omz:plugins:nvm' autoload yes     # 注册 .nvmrc chpwd 钩子
zstyle ':omz:plugins:nvm' silent-autoload yes

source $ZSH/oh-my-zsh.sh
# oh-my-zsh 内部统一调用一次 compinit，覆盖所有 fpath

• 移除手动 source nvm.sh（插件已处理）
• 移除自定义 load-nvmrc 函数（插件内置了相同的 chpwd 钩子实现）
• 移除两处多余的 compinit 调用

结果

指标	修复前	修复后
启动时间	1.08s	0.20s
compinit 调用	3次	1次
compdef 调用	1610次	12次
nvm 启动加载	立即（427ms）	延迟（0ms）

5.4 倍加速。Cursor 的 Shell integration 也从 Basic 恢复到了 Full。

差点翻车的地方

修复过程中犯了一个有意思的错误。oh-my-zsh nvm 插件有个功能：进入包含 .nvmrc 的目录时自动切换 Node 版本。我在配置中写了：

zstyle ':omz:plugins:nvm' auto-use yes    # 错误！

这个选项名是我"想当然"写的。实际上插件源码里根本没有 auto-use 这个选项，正确的选项名是 autoload：

# nvm.plugin.zsh 第 40 行
if ! zstyle -t ':omz:plugins:nvm' autoload; then
    unfunction _omz_nvm_setup_autoload
    return
fi

zstyle 不会对无效的键名报错——它只是静默地返回"没设置"。所以 .nvmrc 自动切换在修复后失效了，而我完全没有察觉，直到手动测试。

这就引出了一个教训。

教训：zstyle 的静默失败

zstyle 是 zsh 的一个通用配置机制，类似于一个键值存储。它的设计哲学是宽松的——你可以设置任意键名，查询任意键名，不存在的键只是返回空值，不会报错。

zstyle ':omz:plugins:nvm' whatever-i-want yes   # 不报错
zstyle -t ':omz:plugins:nvm' whatever-i-want     # 返回 false，不报错

这种设计在灵活性和容错性之间做了取舍：

• 好处：插件可以自由定义自己的 zstyle 键，不需要提前注册
• 坏处：拼写错误、选项名记错，完全不会有任何提示

这和 CSS 的行为很像——写一个不存在的属性名，浏览器不会报错，只是忽略。但 CSS 至少有 DevTools 可以高亮无效属性。zstyle 没有任何等价的检查机制。

唯一可靠的验证方式：读插件源码。

不是读文档（文档可能过时），不是凭记忆（记忆会出错），是直接 cat 插件的 .plugin.zsh 文件，看它用 zstyle -t 查询的是什么键名。

# 正确的验证方式
grep "zstyle" ~/.oh-my-zsh/plugins/nvm/nvm.plugin.zsh

.zshrc 的熵增定律

回头看这个 .zshrc，它不是一次性写坏的。它是累积变坏的：

1. 最早手动配置了 nvm
2. 后来加了 oh-my-zsh nvm 插件，但没删掉手动配置
3. 再后来写了自定义 load-nvmrc，不知道插件已经内置了
4. Docker Desktop 安装时自动追加了 compinit
5. OPENSPEC 工具也自动追加了一个 compinit

每一步都是"能用"的，每一步都没有出错。但五层叠加下来，启动时间从 0.2 秒膨胀到了 1.08 秒。

这就是 .zshrc 的熵增定律：每个工具只管往里追加，没有工具负责清理。 你的 shell 配置文件会随着时间单调变慢，直到某天你终于感觉到了。

解决方案不是定期手动审查（没人会做这件事），而是：

1. 用 zprof 建立基线：知道正常启动应该多快
2. 理解你用的每个插件：它做了什么，覆盖了哪些手动配置
3. 新工具自动追加的内容，立刻审查：Docker、OPENSPEC 这类工具会静默修改你的 .zshrc

# 建议加到日常检查中
time zsh -i -c exit
# 超过 0.3 秒就该排查了

附：oh-my-zsh nvm 插件完整选项

从源码确认的有效选项（2026.03 版本）：

选项	说明
lazy	延迟加载 nvm，在首次使用 node/npm/nvm 等命令时才真正 source
lazy-cmd	额外的触发延迟加载的命令列表（如 eslint、prettier）
autoload	启用 .nvmrc 自动切换（注册 chpwd 钩子）
silent-autoload	静默切换，不输出 nvm use 的消息

注意：没有 auto-use、auto-switch、auto-load（连字符版）等选项。只有 autoload，一个单词。