VS Code 终端启动报 `compdef` / `function definition file not found` 解决

generated by claude-sonnet-4-6

症状

仅在 VS Code 集成终端中出现，普通终端（Terminal.app、Ghostty 等）不受影响：

compinit: function definition file not found
bashcompinit: function definition file not found
is-at-least: function definition file not found
add-zsh-hook: function definition file not found

原因

VS Code Shell Integration 的注入机制

VS Code 开启 Shell Integration 后，启动终端时会将 ZDOTDIR 指向一个临时目录，该目录包含 VS Code 自己的 .zshenv、.zprofile、.zshrc，再由这些脚本去 source 用户的配置文件。

FPATH 环境变量传递不完整

~/.zprofile 中执行了：

eval "$(/opt/homebrew/bin/brew shellenv)"

brew shellenv 的输出包含：

fpath[1,0]="/opt/homebrew/share/zsh/site-functions";
export FPATH;

export FPATH 会把当前 session 的完整 fpath 导出为环境变量。在完整的 login shell 里，fpath 包含 Homebrew zsh 的函数目录：

/opt/homebrew/Cellar/zsh/5.9.1/share/zsh/functions   ← compinit、add-zsh-hook 等在此
/opt/homebrew/share/zsh/site-functions
...

VS Code 以 GUI 方式启动时（从 Dock、Spotlight 启动），继承的是 macOS launchd 的最小化环境，FPATH 要么不存在，要么只含 /opt/homebrew/share/zsh/site-functions。

zsh 的行为：若环境中存在 FPATH 变量，zsh 直接用它初始化 fpath，跳过内置默认值。brew shellenv 只是在头部插入一条 site-functions，Homebrew zsh 真正的函数目录 /opt/homebrew/Cellar/zsh/5.9.1/share/zsh/functions 始终不在 fpath 里，compinit 等标准函数全部 autoload 失败。

修复方案

在 ~/.zshenv 最顶部加入：

# Ensure Homebrew zsh functions are in fpath (required when VS Code inherits incomplete FPATH)
fpath=("/opt/homebrew/Cellar/zsh/${ZSH_VERSION}/share/zsh/functions" $fpath)
typeset -U fpath

$ZSH_VERSION 由 zsh 自身在任何配置文件执行前就已设置，将 Homebrew zsh 的函数目录显式插入 fpath 头部，不依赖环境继承。typeset -U fpath 去除重复项。

~/.zshenv 在每次 zsh 启动时都会执行（无论 login/non-login、是否有 ZDOTDIR 注入），因此可覆盖所有场景。