[tools] Shell 環境配置：macOS 開發者的 Zsh 工具箱

前言

開發者每天在終端機花的時間比想像中多。這篇記錄一套經過實戰打磨的 zsh 配置，核心原則：模組化、安全預設、現代工具優先。

檔案結構總覽

~
├── .zshrc                  # 主配置：載入 Oh My Zsh、環境變數、source 外部檔案
├── .p10k.zsh               # Powerlevel10k 主題配置
├── .zsh_aliases            # 所有 alias 集中管理
└── .zsh/
    ├── git_wrapper.zsh     # Git clone 多 SSH key wrapper
    └── functions/
        ├── claude_dev.zsh  # Claude Dev Framework
        ├── ports.zsh       # Port 管理工具
        ├── aws_tools.zsh   # AWS 相關函數
        ├── django_tools.zsh
        ├── docker_tools.zsh
        ├── git_release.zsh
        ├── k8s_tools.zsh
        ├── python_tools.zsh
        ├── redis_tools.zsh
        └── utils.zsh       # 通用工具函數

.zshrc 本身只負責「載入」，alias 和函數都拆到外部檔案，改某一類設定時不影響其他部分。

.zshrc 主配置

# === Oh My Zsh ===
export ZSH="$HOME/.oh-my-zsh"
ZSH_THEME="powerlevel10k/powerlevel10k"
 
plugins=(
  git
  zsh-completions
  zsh-autosuggestions
  zsh-syntax-highlighting
  zsh-z
)
 
source $ZSH/oh-my-zsh.sh
[[ -f ~/.p10k.zsh ]] && source ~/.p10k.zsh
 
# === 開發環境 ===
# Node.js (nvm)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && source "$NVM_DIR/nvm.sh"
 
# pnpm
export PNPM_HOME="$HOME/Library/pnpm"
export PATH="$PNPM_HOME:$PATH"
 
# Python (pyenv)
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
 
# direnv / OpenJDK / MySQL Client / Google Cloud SDK
eval "$(direnv hook zsh)"
export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"
export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"
source "$(brew --prefix)/share/google-cloud-sdk/path.zsh.inc"
 
# === 載入外部模組 ===
[[ -f ~/.zsh_aliases ]] && source ~/.zsh_aliases
for f in ~/.zsh/functions/*.zsh; do source "$f"; done
[[ -f ~/.zsh/git_wrapper.zsh ]] && source ~/.zsh/git_wrapper.zsh

Plugin	用途
zsh-autosuggestions	根據歷史紀錄灰字提示，按 → 接受
zsh-syntax-highlighting	即時語法高亮，打錯命令會變紅
zsh-z	根據使用頻率快速跳目錄
zsh-completions	額外的 tab 補全定義

Alias 分類

所有 alias 集中在 ~/.zsh_aliases，依用途分區。以下按類別列出。

基礎 Shell & 導航

alias ll='ls -alF'           alias l='ls -CF'
alias ..='cd ..'              alias ...='cd ../..'
alias grep='grep --color=auto'
alias h='history'             alias j='jobs -l'
alias rm='rm -i'              alias mv='mv -i'              alias cp='cp -i'
alias docs='cd ~/Documents'   alias dls='cd ~/Downloads'
alias desk='cd ~/Desktop'     alias work='cd ~/work'

rm/mv/cp -i 是安全預設——破壞性操作都會先確認一次。

Docker & Kubernetes

# Docker
alias dps='docker ps'         alias dpa='docker ps -a'
alias dstart='docker start'   alias dstop='docker stop'
alias drm='docker rm'         alias dlogs='docker logs -f'   alias dexec='docker exec -it'
 
# Kubernetes
alias k='kubectl'             alias kga='kubectl get all'
alias kgs='kubectl get svc'   alias kd='kubectl describe'
alias kl='kubectl logs -f'    alias kdel='kubectl delete'

網路 & 系統

alias ping='ping -c 5'
alias myip='curl -s ifconfig.me'
alias mynet='ifconfig | grep "inet "'
alias flushdns='sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder'
alias ports='lsof -i -P -n | grep LISTEN'
alias top='htop'
alias cpu='top -l 1 | head -n 10'
alias mem='top -l 1 | grep PhysMem'
alias df='df -h'              alias du='du -sh'
alias lsapp='mdfind "kMDItemKind == Application" | sort'
alias purge='sudo purge'      alias o='open .'

Tree 系列

alias tree='tree --dirsfirst'  alias treed='tree -d'
alias tree1='tree -L 1'       alias tree2='tree -L 2'       alias tree3='tree -L 3'
alias treea='tree -a'
alias treex='tree --prune -I "node_modules|.git|__pycache__"'
alias trees='tree --prune -P "*.sh"'
alias treeg='tree --prune -P "*.go"'
alias treem='tree --prune -P "*.md"'

treex 排除 node_modules、.git、__pycache__ 後看專案結構才有意義。

搜尋（fd + ripgrep）

alias f='fd'                  alias ffd='fd -t f'            alias fdd='fd -t d'
alias rga='rg --hidden --no-ignore'
alias rgf='rg -l'             alias rgg='rg --glob'
alias rgc='rg -c'             alias rgs='rg -S'              alias rgv='rg -v'

fd 取代 find、rg 取代 grep，速度差距是數量級的。

SSH & Tmux

# SSH
alias sshconf='vim ~/.ssh/config'     alias sshgen='ssh-keygen -t ed25519 -C'
alias sshlist='ssh-add -l'            alias sshadd='ssh-add'
alias sshdel='ssh-add -D'
 
# Tmux - Session
alias tns='tmux new-session -s'       alias tls='tmux list-sessions'
alias tat='tmux attach -t'            alias tks='tmux kill-server'
alias tksess='tmux kill-session -t'   alias trs='tmux rename-session -t'
# Tmux - Window
alias tnw='tmux new-window -n'        alias tlw='tmux list-windows'
alias tkw='tmux kill-window -t'       alias trw='tmux rename-window -t'
alias tsw='tmux select-window -t'
# Tmux - Pane
alias tsp='tmux split-window -h'      alias tspv='tmux split-window -v'
alias tnp='tmux select-pane -t'       alias tpp='tmux select-pane -t :.-'
alias tkp='tmux kill-pane -t'         alias trp='tmux resize-pane'
alias tspw='tmux swap-pane'           alias trl='tmux rotate-window'

開發工具 & AI

alias venv='python3 -m venv .venv && source .venv/bin/activate'
alias ni='npm install'         alias nis='npm install --save'
alias nr='npm run'             alias ns='npm start'           alias nt='npm test'
alias zshconfig='vim ~/.zshrc' alias reload='source ~/.zshrc'
alias claude='npx @anthropic-ai/claude-code'

自定義函數

Git Clone Wrapper：多 SSH Key 支援

多個 GitHub/GitLab 帳號各用不同 SSH key 時，clone 需要指定用哪一把。這個 wrapper 用 flag 切換：

# ~/.zsh/git_wrapper.zsh
# git clone <repo-url> --work   → 使用工作 SSH key
# git clone <repo-url> --origin → 使用個人 SSH key
# git clone <repo-url> --ment   → 使用第三組 SSH key

原理：攔截 git clone，根據 flag 替換 SSH config 中對應的 Host 別名，SSH 自動選到正確的 key。

Claude Dev Framework

# ~/.zsh/functions/claude_dev.zsh
# gclone              - 智慧 clone（整合 Git Wrapper）
# init-claude          - 初始化專案的 Claude 設定
# claude-dev-export    - 匯出開發環境設定
# claude-dev-update    - 更新 Claude Code 工具
# claude-dev-info      - 顯示當前開發環境資訊

Port 管理工具

# ~/.zsh/functions/ports.zsh
# portman  - 互動式 port 管理（查看 / 關閉）
# pk <port> - 直接 kill 佔用指定 port 的 process
# pls       - 列出所有 LISTEN 中的 port

「port 被佔了」是開發時最常見的問題之一，pk 3000 一行解決。

其他函數檔案

檔案	用途
aws_tools.zsh	AWS CLI 常用操作封裝
django_tools.zsh	Django manage.py 快捷指令
docker_tools.zsh	Docker compose、清理等進階操作
git_release.zsh	Semantic version tag + release 流程
k8s_tools.zsh	Kubernetes context 切換、資源監控
python_tools.zsh	virtualenv、pip 批次操作
redis_tools.zsh	Redis CLI 連線、常用查詢
utils.zsh	通用工具（解壓縮、編碼轉換等）

Server 管理常用指令

配好 alias 是第一步，但真正上 server debug 的時候，你需要知道這些原始指令在幹嘛。這一節整理前端工程師也該會的 server 管理指令——不是每天都用，但出事的時候能自己查、自己修，不用每次都等後端或 SRE。

磁碟用量

Server 跑到磁碟滿了是很常見的事故：

# 查看整體磁碟使用量
df -h
 
# 查看當前目錄下各資料夾的大小
du -sh *
 
# 找出佔空間最大的前 10 個資料夾
du -sh * | sort -rh | head -10

檔案操作與 Log 追蹤

# 即時追蹤 log（-f = follow，部署完盯著看有沒有報錯）
tail -f /var/log/app.log
 
# 搜尋 log 中的錯誤（顯示行號 + 前後 3 行 context）
grep -n -C 3 "TypeError" /var/log/app.log
 
# 遞迴搜尋整個資料夾
grep -r "keyword" /path/to/folder

tail -f 大概是 debug 時最常用的指令。部署完開一個 terminal 盯著 log，馬上就能看到有沒有報錯。如果你的 shell 已經裝了 rg（ripgrep），搜尋速度會比 grep 快一個數量級。

系統監控

free -m        # 記憶體使用量（MB）
uname -a       # 系統基本資訊
nproc          # CPU 核心數

上面 alias 區已經把 top 映射到 htop，直接打 top 就能用更好的介面。

Windows 對應指令

如果你的開發機是 Windows，對應的指令長這樣：

# 查詢 Port 使用情況
netstat -ano | findstr :8080
 
# 終止程序（先用上面的指令找到 PID）
taskkill /F /PID <PID>

SSH 遠端連線速查

上面 alias 區已經有 sshgen、sshlist 等快捷指令。這裡補充幾個 SCP 檔案傳輸的用法：

# 本機 → 遠端
scp local-file.txt user@server-ip:/remote/path/
 
# 遠端 → 本機
scp user@server-ip:/remote/file.txt ./local-path/

小提醒：設定好 ~/.ssh/config 可以省掉很多重複打字。每台 server 設一個別名，之後 ssh my-server 就能連了。上面的 Git Clone Wrapper 也是基於這個機制運作。

設計重點

1. 模組化分離 — .zshrc 只負責載入，新增工具只要加 .zsh 檔，不動主配置。
2. 安全預設 — rm/mv/cp 加 -i，比 trash-cli 更通用。
3. 多 SSH Key 管理 — Git Clone Wrapper 在 clone 時選身份，不用手動改 GIT_SSH_COMMAND。
4. 現代工具替代 — fd/rg/htop 取代 find/grep/top，預設忽略 .gitignore、速度更快。
5. AI 工具整合 — claude alias 直接呼叫 Claude Code，配合 claude_dev.zsh 管理開發流程。

---

核心思路：讓常用操作變成肌肉記憶等級的短指令，同時保持模組化讓配置能跟著技術棧演進。整理 dotfiles 建議從 alias 分類開始——把每天打超過三次的命令都縮短，效果立竿見影。