Skip to Content
OSTerminalzsh config

统一 zsh 配置

这份配置用于 Linux 和 macOS 共用。把它放在 zsh framework 初始化之后：zimfw 先完成 ~/.zim/init.zsh 初始化，oh my zsh 先完成 source $ZSH/oh-my-zsh.sh，再放下面这段。

默认 .zshrc 只保留 Starship、zoxide、fzf 和 alias。Node、Python venv、WSL PATH 清理、conda 这类环境相关配置都作为可选插槽，按需用后面的 cat <<'EOF' >> ~/.zshrc 片段追加。

zimfw 推荐片段

如果使用 zimfw，Starship 继续交给 module 管理。zoxide 和 fzf 可以用 zsh-defer 做不加 -t 的异步加载。

zmodule joke/zim-starship
zmodule romkatv/zsh-defer

joke/zim-starship 会缓存 Starship init script 并 zcompile。Starship 是 prompt 初始化， 不建议延迟加载。zoxide 和 fzf 不加固定延时，只让 zsh-defer 在 prompt 后尽快加载；没有 zsh-defer 时同步执行，保证命令存在。

默认 .zshrc

cat <<'EOF' >> ~/.zshrc
 
# ============================================================
# Core
# ============================================================
 
[[ ":$PATH:" == *":$HOME/.local/bin:"* ]] || export PATH="$HOME/.local/bin:$PATH"
 
zsh_defer_or_run() {
  if (( $+functions[zsh-defer] )); then
    zsh-defer "$@"
  else
    "$@"
  fi
}
 
zsh_optional_eval() {
  local init_script
 
  init_script="$("$@" 2>/dev/null)" || return 0
  [[ -n "$init_script" ]] && eval "$init_script"
}
 
# ============================================================
# Frequent interactive integrations
# ============================================================
 
zsh_defer_or_run zsh_optional_eval zoxide init zsh
zsh_defer_or_run zsh_optional_eval fzf --zsh
 
# ============================================================
# Aliases
# ============================================================
 
# zoxide
alias j="z"
alias ji="zi"
 
# Git
alias g="git"
alias gct="git commit"
alias gs="git stash"
alias gr1="git reset --soft HEAD~1"
alias gp="git pull"
alias ggp="git push"
alias gaa="git add ."
alias gch="git checkout"
 
# JavaScript runtime
alias nr="npm run"
alias br="bun run"
alias bx="bunx"
 
# Python
alias uvpy="uv run python"
alias uvpip="uv pip"
 
# Tools
alias ard="aria2c --summary-interval=10 -x 3 --allow-overwrite=true -Z"
 
if [[ "$OSTYPE" == linux* ]]; then
  alias sdr="systemctl daemon-reload"
  alias sr="systemctl restart"
  alias jl="journalctl -o cat -fu"
fi
 
# ============================================================
# Prompt
# ============================================================
 
zimrc_file="${ZIM_CONFIG_FILE:-${ZDOTDIR:-${HOME}}/.zimrc}"
if [[ -f "$zimrc_file" ]] && grep -q 'zmodule joke/zim-starship' "$zimrc_file"; then
  :
else
  eval "$(starship init zsh)"
fi
 
EOF
 
source ~/.zshrc

可选插槽

fnm

需要 Node.js 版本管理时再追加。zoxide/fzf 优先加载，fnm 放在后面异步加载。

cat <<'EOF' >> ~/.zshrc
 
# ============================================================
# Optional: fnm
# ============================================================
 
zsh_init_fnm() {
  if [[ -z "${XDG_RUNTIME_DIR:-}" || ! -d "$XDG_RUNTIME_DIR" || ! -w "$XDG_RUNTIME_DIR" ]]; then
    export XDG_RUNTIME_DIR="/tmp"
  fi
 
  zsh_optional_eval fnm env --use-on-cd --shell zsh
}
 
zsh_defer_or_run zsh_init_fnm
EOF

fnm 异步时，Starship 首个 prompt 可能读不到 Node 版本；后续 prompt 或进入项目目录后会恢复。 如果必须让 Starship 首屏显示 Node 版本，只能把 fnm 提前到更早的初始化阶段。

Python venv helper

cat <<'EOF' >> ~/.zshrc
 
# ============================================================
# Optional: Python venv
# ============================================================
 
activate_venv() {
  local venv_path="${1:-.venv}"
  local candidate
  local activate=""
  local candidates=(
    "$venv_path"
    "$venv_path/bin/activate"
    "$venv_path/.venv/bin/activate"
  )
 
  for candidate in "${candidates[@]}"; do
    if [[ -f "$candidate" ]]; then
      activate="$candidate"
      break
    fi
  done
 
  if [[ -z "$activate" ]]; then
    print -u2 "No virtual environment activation script found for '$venv_path'."
    return 1
  fi
 
  source "$activate"
}
 
deactivate_venv() {
  if (( $+functions[deactivate] )); then
    deactivate
    return
  fi
 
  print "No active Python virtual environment."
}
 
alias venv="activate_venv"
alias va="activate_venv"
alias vde="deactivate_venv"
EOF

可选 zim-zoxide

如果更想要 zoxide init script 的 cache / zcompile，可以改用 antoineco/zim-zoxide。 这种方式会同步加载缓存文件，首次可键入时间通常不如 zsh-defer 方案，但后续执行更稳定。

zmodule antoineco/zim-zoxide

启用 antoineco/zim-zoxide 后，要删除 .zshrc 里的这行，避免重复初始化：

zsh_defer_or_run zsh_optional_eval zoxide init zsh

加载策略

默认配置只把 zoxide 和 fzf 放进 deferred 队列。队列按注册顺序执行，所以高频跳转和模糊搜索先 入队；fnm、conda 等环境集成通过可选插槽追加，按追加位置决定优先级。

Starship 不做 deferred loading。默认配置会同步检查 ~/.zimrc 是否启用了 zmodule joke/zim-starship；没有启用时才执行 eval "$(starship init zsh)"。

专项工具的 function 仍放在各自页面，例如 nix 的 nxi、nxs、nxgc 这类 helper 继续放在 nix 页面。Node 相关的 WSL PATH 清理放在 Node 版本管理。

验证

zsh -n ~/.zshrc
for i in 1 2 3; do /usr/bin/time -f "zsh startup run $i: %e s" zsh -i -c exit; done
zsh -i -c 'type z; type zi; type j; type ji'
Last updated on
Starshipzimfw