Zsh vs Bash 的配置檔載入順序

理解配置檔的載入順序是結構化拆分的前提。不知道哪個檔案在什麼時機被讀取，就無法判斷設定該放在哪。

Bash 的載入順序

Bash 區分 login shell 和 non-login shell，兩者讀取的檔案不同：

• Login shell（SSH 進來、bash --login）：讀 ~/.bash_profile（如果不存在，依序嘗試 ~/.bash_login → ~/.profile）
• Non-login interactive shell（開一個新終端機視窗）：讀 ~/.bashrc
• 常見做法：在 ~/.bash_profile 裡 source ~/.bashrc，確保設定不管怎麼進來都一致

Zsh 的載入順序

Zsh 的載入鏈比 Bash 更細緻：

1. ~/.zshenv — 每次都讀（login、non-login、script 都會），放環境變數
2. ~/.zprofile — 只有 login shell 讀，對應 Bash 的 ~/.bash_profile
3. ~/.zshrc — interactive shell 讀，放 alias、function、prompt、plugin
4. ~/.zlogin — login shell 在 .zshrc 之後讀（少用）
5. ~/.zlogout — logout 時讀（少用）

實務上 90% 的設定都進 .zshrc，環境變數（PATH、EDITOR）放 .zshenv。

結構化拆分：從單一巨檔到模組化

一個典型的失控 .zshrc 長這樣：PATH 設定、alias、function、plugin 載入、prompt 配置、各種工具的 eval/source 全混在一起，改一個東西要在五百行裡找位置。

模組化的目標是依職責拆檔，.zshrc 本身只負責 source 這些模組：

 1# ~/.zshrc — 只做 source，不放具體設定
 2
 3# 環境變數（PATH 在 .zshenv，這裡放其他 interactive 專用的）
 4source "$HOME/.config/zsh/env.zsh"
 5
 6# Alias
 7source "$HOME/.config/zsh/aliases.zsh"
 8
 9# Function
10source "$HOME/.config/zsh/functions.zsh"
11
12# Plugin manager
13source "$HOME/.config/zsh/plugins.zsh"
14
15# Prompt / theme
16source "$HOME/.config/zsh/prompt.zsh"
17
18# 工具整合（fzf, nvm, pyenv, etc.）
19source "$HOME/.config/zsh/tools.zsh"
20
21# 機器專屬設定（不進 Git）
22[[ -f "$HOME/.config/zsh/local.zsh" ]] && source "$HOME/.config/zsh/local.zsh"

各模組的職責

aliases.zsh — 短指令對映

 1# 檔案操作
 2alias ll='ls -alF'
 3alias la='ls -A'
 4
 5# Git 常用
 6alias gs='git status'
 7alias gd='git diff'
 8alias gco='git checkout'
 9alias gp='git push'
10
11# 導航
12alias ..='cd ..'
13alias ...='cd ../..'

判讀準則：alias 適合「不帶參數的簡單替換」。如果需要參數處理或條件判斷，改用 function。

functions.zsh — 帶邏輯的常用操作

1# 建目錄並進入
2mkcd() {
3    mkdir -p "$1" && cd "$1"
4}
5
6# 在 Git repo 根目錄搜尋
7ggrep() {
8    git grep "$@" "$(git rev-parse --show-toplevel)"
9}

tools.zsh — 第三方工具的初始化

1# fzf
2[[ -f ~/.fzf.zsh ]] && source ~/.fzf.zsh
3
4# nvm
5export NVM_DIR="$HOME/.nvm"
6[[ -s "$NVM_DIR/nvm.sh" ]] && source "$NVM_DIR/nvm.sh"
7
8# pyenv
9command -v pyenv >/dev/null && eval "$(pyenv init -)"

每個工具的 init 前面加存在性檢查（command -v 或 [[ -f ]]），避免在沒裝該工具的機器上報錯。

local.zsh — 機器專屬、不進 Git

1# 公司 VPN 設定
2export CORP_PROXY="http://proxy.corp:8080"
3
4# 只有這台機器需要的 PATH
5export PATH="$HOME/corp-tools/bin:$PATH"

在 dotfile repo 的 .gitignore 裡排除這個檔案。.zshrc 裡用 [[ -f ... ]] && source 確保不存在也不報錯。

章節文章

跨分類引用

• → 模組一：管理策略：stow 的 package 概念怎麼對應 shell 配置的目錄結構
• → 模組一：跨平台共用一個 Repo：path.zsh 和 tools.zsh 裡的 OS 分流做法
• → 模組三：終端機與編輯器：terminal emulator 的配色跟 shell prompt 的配色協調

先裝 Homebrew，它是後面一切的基礎

macOS 本身沒有內建的第三方套件管理工具，而後面幾乎每一項補強（命令列工具、開發語言、甚至部分 GUI App）都靠它安裝。沒有 Homebrew，這份清單的其他項目全部無從裝起，所以它排第一。

安裝過程會要求輸入登入密碼（sudo），並自動下載 Xcode Command Line Tools，畫面可能停住數分鐘屬正常。

1/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

裝完還要把 Homebrew 的執行檔目錄加進 PATH，shell 才找得到 brew 與之後用它裝的工具。Homebrew 的安裝前綴依晶片而異：Apple Silicon 機器裝在 /opt/homebrew、Intel 機器裝在 /usr/local。安裝腳本結尾會印出對應這台機器的設定指令，照它印的路徑寫進 ~/.zprofile 讓每次開 shell 都生效。以下以 Apple Silicon 為例，Intel 機器把前綴換成 /usr/local 即可：

1echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
2eval "$(/opt/homebrew/bin/brew shellenv)"

這一步做完，驗證安裝成功：

1brew --version   # 應印出 Homebrew 4.x.x

版本號印出來，Homebrew 就能當後面所有項目的安裝來源。

把 bash 更新到 5.x

bash 是裝完 Homebrew 後最值得優先換掉的內建工具。macOS 的 /bin/bash 長年凍結在 3.2 系列（2006 年釋出，目前是 patchlevel 57），Apple 不再更新它，原因是 bash 4 改用 GPLv3 授權、Apple 不願隨系統散布。對寫腳本的人來說，這代表 associative array、${var,,} 大小寫轉換、mapfile 等近二十年的語法都用不了。

正確做法是用 Homebrew 另外裝一份新版並排存在，而不是覆寫系統版。/bin/bash 在唯讀的系統卷上、受 SIP（System Integrity Protection）保護，覆寫會被擋下：

1brew install bash

這會把 bash 5.x 裝到 /opt/homebrew/bin/bash，完全不碰 /bin/bash。因為前一步已經把 /opt/homebrew/bin 排在 PATH 前面，用 #!/usr/bin/env bash 起手的腳本就會自動改用新版。裝完驗證一下版本確實切過去：

1env bash --version   # 應顯示 5.x
2/bin/bash --version  # 系統版仍是 3.2.57，沒被動

要留意的是互動 shell 在現代 macOS 預設是 zsh，這一步不影響它。更新 bash 的目的是給 #!/usr/bin/env bash 腳本一個現代執行環境，不是換登入 shell。真要把新版 bash 當登入 shell，才需要額外把它加進 /etc/shells 再 chsh。

把 ~/.local/bin 加進 PATH，放個人腳本

跟專案無關的小工具（例如 disk-report 與 app-report 這類系統診斷腳本）需要一個能在任何地方直接呼叫、又不污染專案 repo 的家。慣例是個人的 ~/.local/bin，把它建好並掛上 PATH。

1mkdir -p ~/.local/bin
2echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
3export PATH="$HOME/.local/bin:$PATH"

目錄建好、PATH 掛上後，確認它確實生效：

1echo "$PATH" | tr ':' '\n' | grep "$HOME/.local/bin"

之後把腳本 symlink 進這個目錄就能直接當指令用。

後續項目

基礎建設到位後，第一個掛上去的實用腳本就是系統診斷：磁碟空間診斷的 disk-report 與 按 App 聚合佔用的 app-report，兩支都 symlink 進 ~/.local/bin 直接當指令用。

這份清單會隨著之後遇到的需求往下增補，新項目接在這裡。原則維持不變：基礎建設排前面，依賴它的補強排後面，每一項都寫清楚「為什麼要做」而不只是貼指令。