zsh-path-skill

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 "$@"; }