範例結構

 1#!/usr/bin/env bash
 2set -euo pipefail
 3
 4DOTFILES_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 5
 6# --- 偵測 OS ---
 7OS="$(uname -s)"
 8
 9install_packages() {
10    if [[ "$OS" == "Darwin" ]]; then
11        command -v brew >/dev/null || {
12            echo "Installing Homebrew..."
13            /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
14        }
15        brew bundle --file="$DOTFILES_DIR/Brewfile"
16
17    elif [[ -f /etc/arch-release ]]; then
18        sudo pacman -Syu --noconfirm
19        sudo pacman -S --needed - < "$DOTFILES_DIR/packages.txt"
20        # AUR 套件需要 AUR helper（假設已安裝 yay）
21        if command -v yay >/dev/null && [[ -f "$DOTFILES_DIR/aur-packages.txt" ]]; then
22            yay -S --needed - < "$DOTFILES_DIR/aur-packages.txt"
23        fi
24
25    elif [[ -f /etc/debian_version ]]; then
26        sudo apt update
27        xargs -a "$DOTFILES_DIR/apt-packages.txt" sudo apt install -y
28    fi
29}
30
31deploy_configs() {
32    if ! command -v stow >/dev/null; then
33        echo "stow not found, skipping config deployment"
34        return 1
35    fi
36    cd "$DOTFILES_DIR"
37    for dir in zsh git nvim tmux hypr waybar; do
38        [[ -d "$dir" ]] && stow -v --target="$HOME" "$dir"
39    done
40}
41
42post_setup() {
43    # 切換預設 shell
44    if [[ "$SHELL" != "$(command -v zsh)" ]] && command -v zsh >/dev/null; then
45        chsh -s "$(command -v zsh)"
46    fi
47
48    # neovim plugin 安裝（headless 模式）
49    if command -v nvim >/dev/null; then
50        nvim --headless "+Lazy! sync" +qa 2>/dev/null || true
51    fi
52}
53
54echo "=== Installing packages ==="
55install_packages
56
57echo "=== Deploying configs ==="
58deploy_configs
59
60echo "=== Post-setup ==="
61post_setup
62
63echo "Done. Log out and back in for shell changes to take effect."

設計原則

冪等性是最重要的性質。跑一次和跑十次結果相同。pacman -S --needed 只安裝缺少的套件、stow 只建立不存在的 symlink、command -v 在工具已存在時跳過安裝（用 command -v 不用 which——後者在最小系統可能不存在）。冪等的 script 可以放心重跑——改了一個配置後重新 deploy，不會弄壞其他已經正確的部分。

失敗可診斷是這支範例為了聚焦結構而省略、但實際該有的性質。bootstrap 在陌生機器上失敗是常態，怎麼讓它在某一步掛掉時留下可定位的痕跡（全輸出 tee 落地 + ERR trap 點名出錯的行與指令），見 可除錯的 bootstrap——那篇是這支腳本的「失敗時看得見」那一層。

偵測 OS 分流處理的是跨平台差異。macOS 用 Homebrew、Arch 用 pacman、Debian 系用 apt——套件管理器不同、套件名稱有時也不同（macOS 的 coreutils 在 Linux 是預裝的）。分流邏輯集中在 bootstrap script 裡，配置檔本身盡量保持跨平台一致。

最少依賴原則：script 本身只依賴 bash 和 curl（幾乎所有系統預裝），其他工具由 script 自己安裝。這確保你可以在一台只有 base system 的機器上直接跑 script。不過「base system 直接跑」有個前提——最小安裝可能連 sudo 都沒有，而 script 裝套件正要靠它。跑這支 script 之前該驗證並補齊的前置工具，見 最小安裝後的工具驗證與補足。

交付完整可用的環境：script 的職責是讓部署完的配置「能直接用」，所以它必須裝齊配置實際引用的每一樣東西，而不是假設它們已經在。一個常見的破綻是把依賴寫進 README 的「dependencies」清單、卻沒在 script 裡實作安裝——例如 .zshrc 引用了 oh-my-zsh、主題、外掛，但 install script 只裝了 zsh 本身，結果 stow 部署完、第一次開 shell 就因為找不到那些東西而報錯。README 列依賴是給人看的、不會被執行；要讓配置真的能用，那些依賴得由 script 自己裝（例如把外掛 git clone 進對應位置）。檢查方式是反過來從配置出發：把每個 config 會 source 或引用的外部東西列出來，逐一確認 script 有沒有負責把它裝上。

可部分執行的結構：拆成 function，允許只跑某一段。除錯時只想重新 deploy 配置、不想重裝套件，直接呼叫 deploy_configs 就好。進一步可以把每段拆成獨立 script（scripts/install-packages.sh、scripts/deploy-configs.sh），bootstrap 入口只是依序呼叫它們。

套件清單管理

dotfile repo 管的是「配置」，但配置的前提是軟體已安裝。沒有附帶套件清單的 dotfile repo 是不完整的重建指令——你 clone 下來卻不知道該先裝什麼。

macOS：Brewfile

 1# Brewfile
 2tap "homebrew/cask-fonts"
 3
 4# CLI 工具
 5brew "git"
 6brew "neovim"
 7brew "tmux"
 8brew "stow"
 9brew "ripgrep"
10brew "fd"
11brew "fzf"
12brew "zsh"
13
14# GUI app
15cask "wezterm"
16cask "rectangle"
17cask "font-jetbrains-mono-nerd-font"

brew bundle dump 從當前系統產生 Brewfile、brew bundle 照 Brewfile 安裝。Brewfile 區分三種來源：brew（CLI formula）、cask（GUI app）、tap（第三方 repo）。把 Brewfile 放在 dotfile repo 根目錄，bootstrap script 用 brew bundle --file=./Brewfile 安裝。

Arch Linux：packages.txt

1# 匯出已安裝的 explicitly installed 套件
2pacman -Qqe > packages.txt
3
4# AUR 套件另外記
5pacman -Qqem > aur-packages.txt

-Qqe 只列出使用者主動安裝的套件（不含被依賴自動拉進來的），這是你實際需要管理的範圍。-Qqem 進一步篩出外部來源（AUR）。還原時用 pacman -S --needed - < packages.txt，--needed 跳過已安裝的。

Ubuntu/Debian

apt 的匯出格式比較雜。務實做法是手動維護一份清單檔（apt-packages.txt），每行一個套件名，用 xargs -a apt-packages.txt sudo apt install -y 安裝。比起 apt list --installed 的完整匯出（包含大量系統依賴），手動維護的清單更乾淨、更容易讀懂。

為什麼套件清單要進 repo

一個常見的失敗模式：dotfile repo 裡有完整的 neovim 配置，clone 到新機器後發現 neovim 沒裝、ripgrep 沒裝、字型沒裝，配置跑起來全是 error。套件清單跟配置檔放在同一個 repo，bootstrap script 才能先裝套件再 deploy 配置，形成完整的重建鏈路。

第一步：分「連不到」還是「連得到但被拒」

錯誤訊息本身就能分層，不用猜：

• 訊息提到主機名解不出、連線逾時、retrieving file 失敗 → 連不到，往網路 / DNS / mirror 查。
• 訊息提到 database lock、signature、trust、conflicting、partial → 連得到、封包也拿到了，是套件管理器的狀態問題。

判準是問一句：「它到底有沒有成功連上 mirror？」有連上才談得到簽章、相依、db 狀態；連都沒連上，那些都還輪不到。剛裝好的最小系統最常見的是前者——網路設定還沒到位。

連不到那層：從實體介面往上查到域名

網路不通有好幾層，從最底層往上逐層確認，哪一層斷了一目了然。這條鏈跟最小安裝後的驗證裡的網路檢查同源，這裡聚焦在「抓套件失敗」這個症狀上：

1ip -brief a              # 1. 有沒有拿到 IP？介面 UP 且有位址
2ping -c1 8.8.8.8         # 2. IP 層對外通不通？（直接打 IP、跳過 DNS）
3getent hosts archlinux.org   # 3. 域名解得出來嗎？
4timedatectl              # 4. 時間對嗎？（影響下一層的簽章驗證）

第 2 步通、第 3 步不通 = DNS 問題，這是最小安裝最典型的落點：IP 層明明通（ping 8.8.8.8 有回應），但域名解不出來，因為 /etc/resolv.conf 還沒設 nameserver。這時 pacman 會卡在解析 mirror 主機名。修法是給系統一個 resolver——臨時可直接寫 /etc/resolv.conf（nameserver 1.1.1.1）。先看它是什麼（ls -l /etc/resolv.conf）：啟用了 systemd-resolved 或 NetworkManager 的系統上它是那些服務管理的 symlink，手寫會被覆蓋，治本要透過該網路管理服務設定 DNS；裸 Arch 最小安裝若沒啟用這些服務，它通常就是一個普通檔案，手寫即持久生效。

mirror 逾時 / 抓不到：DNS 通了、但某個 mirror 慢或掛了。換 /etc/pacman.d/mirrorlist 到地理近且快的鏡像（實測不同 mirror 速度可差數倍）。這也接回安裝選項判讀裡選 mirror 的決策——裝機當下選錯 mirror，這裡就會慢。

連得到但被拒那層：pacman 自己的狀態

連上 mirror、封包也拿到了卻失敗，問題在 pacman 的本地狀態或簽章驗證。這幾種各有明確徵兆與修法：

database lock：上次沒清乾淨的殘留

error: failed to init transaction (unable to lock database)。pacman 用 /var/lib/pacman/db.lck 這個鎖檔保證同時只有一個 pacman 在動資料庫；上次 pacman 被中斷（斷電、Ctrl+C、當掉）沒清掉鎖檔就會殘留。先確認真的沒有 pacman 在跑（pgrep -x pacman），確認沒有再刪鎖檔：

1pgrep -x pacman && echo "有 pacman 在跑、別刪" || sudo rm /var/lib/pacman/db.lck

先查再刪這個順序重要——盲刪鎖檔時如果真的有另一個 pacman 在跑，兩個同時寫資料庫會弄壞它。

簽章 / keyring 過期：十之八九是時間不對

invalid or corrupted package (PGP signature) 或 signature is unknown trust。pacman 驗證每個套件的 GPG 簽章，驗證失敗最常見的根因是系統時間不對——這正是第一步要 timedatectl 的原因。時間差太多（新裝的 VM、主機板電池沒電的老機器）會讓「簽章的有效期」判斷錯誤，明明有效的簽章被判過期。先校時：

1sudo timedatectl set-ntp true     # 開 NTP 自動校時（SSH 進最小系統無 polkit 互動代理、裸跑會被拒，要 sudo）

時間對了還失敗，才是 keyring 本身的問題（archlinux-keyring 太舊）：sudo pacman -Sy archlinux-keyring 更新 keyring，必要時 sudo pacman-key --refresh-keys。順序是先校時再動 keyring，因為時間不對時連 keyring 都更新不了。

partial upgrade：只同步不升級造成的相依斷裂

conflicting dependencies 或裝完某個套件後系統行為異常。根因是在 rolling 發行版上只做了 pacman -Sy（同步資料庫）就裝新套件，卻沒 -u（升級既有套件）——新套件依賴新版函式庫，但系統還是舊的，相依對不上。Arch 只支援 full upgrade：一律 pacman -Syu，永遠不要單獨 -Sy 之後裝東西。這條規則救掉這一整類故障。

stale db 404：裝機當下的資料庫已經過期

error: failed retrieving file '...' 404，而且換好幾個 mirror 都一樣。這是 rolling 發行版特有的時序陷阱：Arch 的 mirror 不保留舊版檔案，你裝機時 ISO 內建的套件資料庫指向的檔名，可能幾天內就被輪替掉了——資料庫說有這個檔、mirror 上已經沒有。修法跟上一條同源：pacman -Syu 先把資料庫同步到最新，檔名對上了就抓得到。這也是為什麼「一律 -Syu」是 Arch 的鐵律，而不只是建議。

判讀總表

下一步

• 這幾步用到的網路驗證，完整版在最小安裝後的工具驗證與補足。
• 裝機時選 mirror / locale / 時區的決策，見Linux 安裝選項判讀。
• 跨發行版時「這個套件名 / 這個旗標在別的發行版叫什麼」的差異判讀，見平台與發行版差異的判讀地圖。
• 套件抓下來了、但 bootstrap 腳本本身失敗要 debug，見可除錯的 bootstrap。
• 系統跑起來後才出的套件問題（AUR 建置失敗、-bin 包 soname 斷裂等），屬除錯範疇，見Linux 除錯與診斷。