本文的做法基於 GNU Stow——將 dotfile repo 的檔案透過 symlink 對應到家目錄的工具（完整說明見管理策略與選型）。一個 repo 跨平台的做法是三層分離，每層處理不同粒度的差異：

第一層：stow 選擇性安裝

Stow 的 package 機制天然支持跨平台。repo 裡同時放 macOS 和 Linux 的配置，安裝時只 stow 該 OS 需要的 package：

1# macOS
2stow zsh git zellij btop broot
3
4# Linux desktop
5stow zsh git zellij btop broot hyprland waybar wofi mako

hyprland、waybar 這些目錄放在 repo 裡但 macOS 不 stow，不會有副作用。bootstrap script 裡用 uname 自動決定要 stow 哪些 package：

1PACKAGES=(zsh git zellij btop broot)
2
3if [[ "$(uname -s)" == "Linux" ]]; then
4    for pkg in hyprland waybar wofi mako hyprlock; do
5        [[ -d "$pkg" ]] && PACKAGES+=("$pkg")
6    done
7fi

第二層：配置檔內的 OS 分流

同一份配置檔裡，用 uname 區分 macOS 和 Linux 的差異。適合處理 PATH、工具初始化路徑這類「同一個用途、不同 OS 路徑」的狀況：

 1# path.zsh
 2typeset -U PATH
 3export PATH="$HOME/.local/bin:$PATH"    # 共用
 4
 5if [[ "$(uname)" == "Darwin" ]]; then
 6    # Homebrew Ruby、FVM、Android SDK（macOS 路徑）
 7    [[ -d "/opt/homebrew/opt/ruby/bin" ]] && export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
 8    export PATH="$HOME/fvm/default/bin:$PATH"
 9    export PATH="$PATH:$HOME/Library/Android/sdk/emulator"
10fi
11
12if [[ "$(uname)" == "Linux" ]]; then
13    # Android SDK（Linux 路徑）
14    [[ -d "$HOME/Android/Sdk/emulator" ]] && export PATH="$PATH:$HOME/Android/Sdk/emulator"
15fi

1# tools.zsh — autojump 的 source 路徑在兩個 OS 不同
2if [[ "$(uname)" == "Darwin" ]]; then
3    [ -f /opt/homebrew/etc/profile.d/autojump.sh ] && . /opt/homebrew/etc/profile.d/autojump.sh
4else
5    [ -f /usr/share/autojump/autojump.sh ] && . /usr/share/autojump/autojump.sh
6fi

每個路徑加 [[ -d ]] 或 [ -f ] 存在性檢查——即使在正確的 OS 上，如果該工具沒裝也不會報錯。

第三層：local.zsh 放機器專屬設定

不是「macOS 的設定」而是「這台特定機器的設定」——工作專案 alias、公司 VPN proxy、只有這台機器需要的 PATH——放在 ~/.config/zsh/local.zsh，不進 Git。

1# .zshrc 裡的載入方式
2[[ -f "$HOME/.config/zsh/local.zsh" ]] && source "$HOME/.config/zsh/local.zsh"

1# ~/.config/zsh/local.zsh（不在 repo 裡，每台機器自己建）
2alias unimall-dev='cd ~/project/unimall_shop && ./scripts/run_commands.sh dev'
3alias unipos-dev='cd ~/project/unipos && ./scripts/run_commands.sh dev'

Repo 裡放一份 local.zsh.example 作為範本，.gitignore 裡排除 local.zsh 本身。

套件清單也分 OS

1~/dotfiles/
2├── Brewfile              # macOS: brew bundle dump 產生
3├── packages-arch.txt     # Arch Linux: pacman -Qqe > packages-arch.txt
4└── ...

Bootstrap script 依 OS 讀對應的清單安裝套件。

Stow 跨平台的邊界

這個三層模型適合「配置檔本身大部分通用、差異只在 PATH 和少數工具路徑」的狀況——也就是多數開發者的實際情境。判斷是否需要遷移到 chezmoi 的訊號：

• 同一份配置檔裡超過一半的行數是 OS 分流 → chezmoi template 更乾淨
• 需要在配置檔裡注入 secret（API key、token） → chezmoi 的 secret 管理是必要功能
• 管理的機器超過三種 OS/角色組合 → template 的條件判斷比 shell if-else 更可維護

多數情況下 stow + uname + local.zsh 就足夠。

差異的四個層次

套件管理器：每個平台各有原生解

macOS 用 Homebrew、Arch 用 pacman、Debian/Ubuntu 用 apt、Fedora 用 dnf。安裝指令、確認旗標、資料庫同步模型都不同，其中兩個差異會直接咬到自動化腳本：

• 非互動旗標不對稱：apt 的慣例是 -y，pacman 是 --noconfirm。腳本只寫了其中一邊，換平台就會卡在確認提示——非 TTY 環境下（SSH 一行式、CI、無人值守）沒人回答 [Y/n]，pacman 直接以錯誤結束。
• 資料庫同步模型不同：Arch 是 rolling release 且鏡像不保留舊版檔案，裝機當下的套件資料庫幾天內就會指向已被輪替掉的檔名，安裝時收到 404（failed retrieving file）。修法是安裝前先 pacman -Syu 同步資料庫並全系統升級——只 -Sy 不 -u 會造成 partial upgrade（新資料庫裝新套件、舊系統缺新依賴）。Debian stable 的套件庫凍結、沒有這個時序問題，但代價是版本舊。

套件名稱：同一個工具、各發行版各叫各的

Debian 的重命名還會連執行檔一起改（fdfind、batcat），所以連 shell alias 與腳本內的指令呼叫都要跟著分歧。維護跨發行版清單的可靠做法是逐台實測建立——憑印象抄一份對照表，漂移只是時間問題。

套件存在性：有些概念只存在於特定平台

Hyprland 在 Arch 官方 repo、Fedora 要 COPR、Debian stable 沒有；Quickshell 只有 Arch 打包。反過來，macOS 的 cask app（GUI 應用程式）概念在 Linux 對應的是各桌面環境自己的生態。這層差異沒有翻譯的空間——桌面層的清單是平台專屬的維護對象。

存在性差異還有一個容易漏看的軸：CPU 架構。發行版 repo 有這個工具、不代表它在你的架構上存在——尤其是專有軟體的二進位發行。實測案例：Arch aarch64（ALARM）的 repo 有 spotify-launcher（工具本身有 aarch64 建置），但它要下載的 Spotify 官方 client 只發 x86_64/i386 deb，實跑直接回報 There are no packages for your cpu's architecture (cpu="aarch64", supported=["amd64", "i386"])。這類失敗的判讀重點是分清「工具沒打包」跟「工具打包了、它依賴的專有 blob 沒有這個架構」——前者可能有 AUR / 第三方 repo 補、後者只能找替代路徑（Spotify 的替代是 Web Player + 從 ChromeOS 鏡像抽出的 arm64 Widevine CDM）。DRM、GPU driver、印表機 driver 這類含專有二進位的軟體，在非 x86_64 架構上都要先查架構支援再排進安裝清單。

版本節奏：rolling 與 stable 的行為差

Arch rolling 永遠最新，Debian stable 的同名工具可能舊兩年。版本差會讓 config 語法對不上（新版工具的設定選項在舊版不存在）、也會讓「照著文件做卻失敗」——文件寫的是新版行為。除錯時看到「同一份 config 在 A 機器能跑、B 機器報錯」，先比對兩邊的工具版本再懷疑 config 本身。

除錯前先定平台

跨平台差異對除錯的意義：判讀工具與修法都是平台相依的，先確認自己站在哪，再開始查。 三條指令建立座標：

1cat /etc/os-release        # 發行版與版本（Linux）
2uname -m                   # CPU 架構：x86_64 / aarch64（套件生態差很多）
3command -v pacman apt-get dnf brew   # 哪個套件管理器在場

架構那條容易被忽略：aarch64（ARM）的套件生態比 x86_64 小——Homebrew on Linux 對 aarch64 沒有預編譯 bottle、AUR 部分套件不支援 ARM。在 ARM 機器上照 x86 的教學走，會在意想不到的地方碰壁。

Bootstrap 的分歧設計判準

把差異收進腳本架構的三條判準，決定每段邏輯住在哪：

1. 安裝手段跨平台一致（git clone、curl installer、stow 部署）→ 進共通層，一份邏輯全平台用
2. 只是套件名或套件管理器不同 → 各平台一份安裝腳本 + 一份套件清單，獨立維護、分歧不寫進共通層的 if/else
3. 概念只存在於某平台（Hyprland、cask）→ 只出現在該平台清單的桌面層

這個切法的維護成本結構：共通層改一次全平台生效；平台層只在你真的用那個平台時才付維護成本。沒有實測機器的發行版不預先建清單——那種清單沒有實測支撐、注定漂移。

統一層的誘惑與代價

「用一個跨平台套件管理器統一所有機器」聽起來能消掉整個分歧層，實際的適用邊界很窄。Homebrew 支援 Linux，但它在 Arch 上會建一套與 pacman 平行的套件世界（獨立 prefix、重複的函式庫、PATH 互搶），而且對 aarch64 Linux 沒有 bottle、全部從原始碼編譯。它真正的適用場景是「發行版套件太舊」（如 Ubuntu LTS 上要新版工具）或「沒有 root 權限」。Nix 能做到真正的跨平台一致，代價是整套心智模型重學。判準是：分歧層的維護成本（每個發行版一份清單）低於統一層的引入成本時，保持原生套件管理器 + 分平台清單。

下一步路由

• Bootstrap 腳本本身的設計（log 落地、錯誤定位）見可除錯的 bootstrap
• 最小系統缺什麼、怎麼驗證見最小安裝後的工具驗證與補足
• 出問題時的判讀紀律見 Linux 除錯與診斷
• dotfile repo 怎麼同時服務 macOS 與 Linux 見一個 repo 管理跨平台環境