zsh-path

Zsh PATH 管理技能

此技能提供有关在 zsh 中管理 PATH 环境变量的全面指导，包括排查命令缺失问题、添加新工具以及整理 shell 配置。

何时使用此技能

在以下情况下使用此技能：

• 已安装的工具出现“command not found”错误
• 将新工具添加到 PATH（bun、nvm、cargo、go、Python venv 等）
• 验证和审查当前的 PATH 条目
• 整理 .zshrc 和 .zshrc.local 中的 PATH 配置
• 排查与 PATH 相关的 shell 启动问题
• 设置版本管理器（nvm、pyenv、rbenv）

诊断命令

检查当前 PATH

# List all PATH entries
echo $PATH | tr ':' '\n'

# Check if specific command is in PATH
which bun 2>/dev/null || echo "bun not found in PATH"

# Find where a command is installed
command -v node
type -a python

验证 PATH 条目

# Check for broken/non-existent PATH entries
echo $PATH | tr ':' '\n' | while read p; do
  [[ -d "$p" ]] || echo "MISSING: $p"
done

# Check for duplicate PATH entries
echo $PATH | tr ':' '\n' | sort | uniq -d

常见工具的 PATH 配置

Bun（JavaScript 运行时）

# Add to .zshrc
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

默认位置：~/.bun/bin/bun

NVM（Node 版本管理器）

# Add to .zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

默认位置：~/.nvm/

注意： NVM 是 shell 函数，而非二进制文件。它会动态修改 PATH，使其指向当前启用的 Node 版本。

Python 虚拟环境

# Add to .zshrc for global tools venv
export PATH="$HOME/.venv/tools3/bin:$PATH"

# For pyenv
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Rust/Cargo

# Add to .zshrc
export PATH="$HOME/.cargo/bin:$PATH"

Go

# Add to .zshrc
export GOPATH="$HOME/go"
export PATH="$GOPATH/bin:$PATH"

Homebrew（macOS）

# Intel Mac
export PATH="/usr/local/bin:$PATH"

# Apple Silicon Mac
export PATH="/opt/homebrew/bin:$PATH"
eval "$(/opt/homebrew/bin/brew shellenv)"

本地 bin 目录

# User-local binaries
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"

文件组织最佳实践

.zshrc（团队/共享配置）

在 .zshrc 中保留：

• Oh My Zsh 配置
• 常用团队别名
• 标准 PATH 添加项（homebrew、本地 bin）
• 插件配置

# ===== ZSH-TOOL MANAGED SECTION BEGIN =====
# Team-wide PATH modifications
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"

# Bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

# NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# ===== ZSH-TOOL MANAGED SECTION END =====

# Load local customizations
[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local

.zshrc.local（个人/特定机器配置）

在 .zshrc.local 中保留：

• 特定机器的 PATH 条目
• 个人工具配置
• 实验性设置
• 可能覆盖键绑定的集成

# Machine-specific tools
export PATH="/opt/custom-tool/bin:$PATH"

# Personal integrations
if command -v atuin >/dev/null 2>&1; then
  eval "$(atuin init zsh)"
fi

PATH 顺序很重要

PATH 会从左到右进行搜索。匹配到的第一个结果会生效。

# This order means ~/.local/bin takes priority over system bins
export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"

推荐的 PATH 顺序

1. 项目专属 bin 目录（由 direnv 添加）
2. 用户本地 bin 目录（~/.local/bin、~/bin）
3. 语言版本管理器（nvm、pyenv、rbenv）
4. 包管理器（homebrew、cargo）
5. 系统路径（/usr/local/bin、/usr/bin）

故障排查

安装后找不到命令

# 1. Find where tool was installed
ls -la ~/.bun/bin/bun 2>/dev/null
ls -la ~/.cargo/bin/rustc 2>/dev/null
ls -la ~/.nvm/versions/node/*/bin/node 2>/dev/null

# 2. Check if PATH includes the directory
echo $PATH | tr ':' '\n' | grep -E "(bun|cargo|nvm)"

# 3. Add missing PATH entry to .zshrc

# 4. Reload shell
source ~/.zshrc
# or
exec $SHELL

PATH 更改未生效

# Check which file sets the variable
grep -r "export PATH" ~/.zshrc ~/.zshrc.local ~/.zprofile 2>/dev/null

# Source the correct file
source ~/.zshrc

# Or start fresh shell
exec $SHELL

启动钩子错误

常见原因：

• 钩子使用的工具缺少 PATH 条目
• 对不存在目录的引用已失效
• 版本管理器未找到预期版本

# Debug startup
zsh -x 2>&1 | head -100

# Check for errors in specific config
bash -n ~/.zshrc

PATH 条目重复

# Remove duplicates (add to .zshrc)
typeset -U PATH path

验证命令

更改 PATH 后：

# Reload configuration
source ~/.zshrc

# Verify tool is accessible
which bun && bun --version
which node && node --version
command -v nvm && nvm --version

# Verify PATH includes new entries
echo $PATH | tr ':' '\n' | grep -E "(bun|nvm|venv)"

快速参考

工具	PATH 条目	检查命令
bun	$HOME/.bun/bin	bun --version
nvm	$NVM_DIR/versions/node/*/bin	nvm --version
cargo	$HOME/.cargo/bin	cargo --version
go	$GOPATH/bin	go version
pyenv	$PYENV_ROOT/bin	pyenv --version
brew (ARM)	/opt/homebrew/bin	brew --version
brew (Intel)	/usr/local/bin	brew --version

常见模式

条件式添加 PATH

# Only add if directory exists
[[ -d "$HOME/.bun/bin" ]] && export PATH="$HOME/.bun/bin:$PATH"

# Only add if command not already available
command -v bun >/dev/null || export PATH="$HOME/.bun/bin:$PATH"

延迟加载以加快启动速度

# Lazy load nvm (faster shell startup)
lazy_load_nvm() {
  unset -f nvm node npm npx
  export NVM_DIR="$HOME/.nvm"
  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
}
nvm() { lazy_load_nvm && nvm "$@"; }
node() { lazy_load_nvm && node "$@"; }
npm() { lazy_load_nvm && npm "$@"; }
npx() { lazy_load_nvm && npx "$@"; }

---

注意事项

• path= 数组与 PATH= 环境变量：未使用 typeset -U 时，赋值会失去唯一性： 数小时后会出现过时的重复条目。在 .zshrc 中尽早运行一次 typeset -U path PATH，将二者绑定并自动去重。
• .zprofile 仅在登录 shell 中运行，.zshrc 则在交互式 shell 中运行： Homebrew 的安装程序建议将 eval "$(brew shellenv)" 添加到 .zprofile 中；非登录交互式 shell（Linux 上大多数终端会话）完全不会执行它。如果子 shell 中缺少命令，请也将其添加到 .zshrc。
• NVM 是 shell 函数，而非二进制文件——which node 会误导你： 执行 nvm use 后，which node 会显示 ~/.nvm/versions/node/vXX/bin/node，但新启动的子 shell 可能什么也不显示，直到再次加载 nvm.sh。通过 bash -c 运行的脚本会完全绕过 nvm。
• 延迟加载 nvm 会拖慢 shebang 中的 npm 调用： 以 #!/usr/bin/env node 开头的脚本会派生一个新 shell；该 shell 会加载 .zshrc，而 .zshrc 又会延迟加载 nvm——每次调用脚本都会增加 500 毫秒以上的耗时。如果你要运行许多 node 脚本，请在启动时加载 nvm。
• source ~/.zshrc 不会撤销此前添加到 PATH 的内容： 重新加载会在不去重的情况下追加内容，因此 PATH 会不断增长。测试 PATH 变更时，务必启动一个新 shell（exec zsh），而不是使用 source。
• Apple Silicon 上位于 /opt/homebrew/bin 的 Homebrew 对 Intel 二进制文件不可见： 以 Rosetta 模式运行的终端（arch -x86_64 zsh）看到的是 /usr/local/bin；同一台机器上会有两个不同的 brew 前缀和两套不同的工具链。