哪些綁 distro、哪些共用

拿到一份 dotfile 要跨 distro 時，先把內容分成兩堆，判準是「換 distro 會不會變」：

• 會變、要下沉到平台層：套件安裝指令（pacman vs apt-get）、套件清單、以及套件名分歧的工具。
• 不會變、留共通層：.zshrc 內容、stow 建 symlink 的邏輯、oh-my-zsh 的 git clone、所有 config 檔本身。

判斷錯的代價是把套件名寫死在共通層——換 distro 就壞。正確形態是共通層只呼叫「裝套件」這個抽象動作，具體套件名交給各平台清單。

落地：入口 detection + 平台清單

工作站的套件集在不同 distro 差異大，適合用入口 detection：安裝腳本開頭偵測 package manager，dispatch 到對應的平台腳本。dotfiles repo 的形態是 install.sh 判斷 OS 後委派給 install-arch.sh / install-macos.sh / install-debian.sh，套件清單各一份（packages/arch-*.txt、packages/debian-*.txt），共通的環境組裝（stow、框架 clone）留在 install.sh。

跨到 Debian 只需要補一支 install-debian.sh 跟對應清單，共通層一行都不用動——這正是抽象層有效的證據。

套件名分歧：裝好不等於叫得動

同一個工具在不同 distro 的名字有好幾種分歧（有哪些形態、為什麼，見 Package Manager 抽象層）。落地時按形態各自處理：

• 套件名不同（fd → fd-find、github-cli → gh）：靠各平台清單逐項對照，不假設同名。
• binary 被改名（fd-find 的 binary 是 fdfind、bat 是 batcat）：.zshrc 按平台補 alias（alias fd=fdfind）——「套件裝好了」不等於「指令叫得動」。
• 名字撞到別的工具（apt install delta 裝到的不是 .gitconfig 要的 git-delta）：別照抄，確認同名同物。

ripgrep 兩邊同名（binary 都是 rg）不用處理，fd / bat 就要按上面吸收。

實作會遇到的狀況與排除

跨到 Debian 實跑時，除了名字分歧，還有幾個操作面的狀況會擋住 bootstrap。先知道怎麼排除：

• 全新映像連 sudo/git 都沒有。乾淨的 Debian 映像預裝極簡，install.sh 要用到的 sudo、git 本身都缺。排除：bootstrap 第一步先 apt-get install -y sudo git，才有辦法 clone repo、跑後續。這是最小映像的預期形態，不是壞掉。

• 清單裡一個沒打包的名字讓整批全滅。apt-get install 是一筆全有或全無的交易，清單塞一個 Debian 沒有的名字（實測 broot、zellij 在 bookworm 沒打包），apt 直接中止，同批存在的工具也一個都沒裝。排除：清單逐項對齊該 distro 實際有的套件，動手前用 apt-get install -s <pkg> 逐一 dry-run 篩掉解不開的。原理見 apt 安裝的交易原子性。

• 某些工具 Debian 根本沒打包。broot、zellij、git-delta、lazygit、yazi 在 bookworm 預設 repo 都不存在（Arch 都有）。排除：把它們移出 apt 清單，改從 GitHub releases 裝——抓對應架構的預編譯檔（curl -L -O <release-url>）、解壓、chmod +x、mv 到 ~/.local/bin（確認它在 PATH）；若走 cargo install，cargo 本身要先用 rustup 裝（裸 Debian 沒有）。原理見 發行版打包粒度。

• 裝個 node 拉進幾百個系統套件。apt install nodejs npm 在 Debian 會連帶 300 多個 node-* 套件（實測 bookworm 一次裝進 402 個新套件、其中 336 個是 node-*）。要避免的是拿系統套件管理器裝語言執行環境。排除：node / python / ruby 這類語言生態走 version manager（fnm / pyenv）在家目錄管，別放進 apt 清單。原理見 發行版打包粒度。

邊界與下一步

桌面層（Hyprland 的 rice，即桌面視覺客製化）的跨 distro 成本遠高於 CLI 層：Hyprland 在 Debian 要較新版才有打包，套件名與可用性都要重驗，所以工作站跨 distro 通常只做到 terminal 層，桌面留在實測過的 Arch。

工作站跨好之後，開發還缺一個對齊 client 線上的 runtime——那是下一篇 對齊 prod 的 runtime container。工作站是你的機器、可以最新；runtime 要退回線上那個凍結的舊形狀，兩者對齊的目標相反。

對齊的載體是 image tag 跟 config，不是主機

Parity 不靠「把主機裝成跟 prod 一樣」達成——你的主機是 Arch 或 macOS 都無所謂。對齊的載體是 container 的 image tag 跟掛進去的 config：

• image tag 釘到 OS 世代：用 php:7.2-fpm-buster 而不是 php:7.2-fpm，把 PHP 版本連同底層 Debian 世代一起凍結（見 Image Tag Pinning）。
• 別為了省體積換 libc：prod 是 Debian（glibc）就別用 php:7.2-alpine（musl），DNS 與原生擴充行為會分岔（見 glibc 與 musl）。
• 服務設定抄 prod：MySQL 的 sql_mode、時區，PHP 的擴充清單與 php.ini，都從線上的權威來源抄、不憑印象填。SSH 進 prod 後用 mysql -N -e "SELECT @@sql_mode" 抓 sql_mode、php -m 列擴充、php -i（或 web 端存一支 <?php phpinfo();）看 php.ini 值；抄回來分別填進 db 的 my.cnf（sql_mode / 時區）、Dockerfile 的 docker-php-ext-install 清單（對照 php -m）、掛進去的 php.ini。

主機不變、只有這幾樣對齊——這是 parity 能在任何工作站上重現的原因。

要逐項比對的維度

跑起來後，用一個 probe 印出 runtime 的每個 parity 維度，跟 prod 逐行比對。每一行對應一個會影響行為的維度：

• PHP 主版 + patch 版
• 時區（PHP 與 MySQL 各一份，跨時區的 NOW() 是常見隱形 bug）
• 擴充清單（要相等、不是涵蓋；多裝的擴充讓本機能跑、prod 掛掉）
• MySQL 版本與 sql_mode（5.7 預設開 ONLY_FULL_GROUP_BY，舊 app 的 SELECT ... GROUP BY 未列全欄位會回 error 1055）

實測基線

dotfiles repo 的 runtimes/php72-mysql57/ 是一個跑得起來的 variant（PHP-FPM + MySQL 5.7 + nginx，docker-compose 組合）。docker compose up -d --build 起來後 curl http://localhost:8080/——probe 是一支 src/index.php、由 nginx 服務，逐行印出每個 parity 維度。arm64 macOS 實測（2026-07）輸出：

1PHP version : 7.2.34
2timezone    : Asia/Taipei
3MySQL ver   : 5.7.44
4sql_mode    : ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,...
5db timezone : +08:00

版本、時區、sql_mode 都跟 config 逐項對齊——這就是 parity 達成的樣子。

凍結舊環境的兩個稅

實跑會撞到兩個「照官方 docs 寫會 build 不起來、只有實機才知道」的問題，兩個都是凍結舊環境特有的：

• Debian buster 已 EOL：套件庫從主 mirror 移到 archive.debian.org，Dockerfile 裡不改 apt source 直接 apt-get update 就 404（exit 100）。要改指 archive 並關掉過期檢查。
• mysql:5.7 無 arm64 原生 image：在 Apple Silicon 主機上要 platform: linux/amd64 走模擬（機制見 QEMU binfmt 跨架構模擬）。這本身也是一種 parity——dev 是模擬 amd64、prod 是原生 amd64，架構對齊。

這兩個稅是 Prod Parity 原則 講的「對齊凍結環境要付的代價」的具體形態：凍結舊版意味著也繼承了它 EOL 與架構支援退場的後果。

什麼時候值得做到逐項

Parity 是有成本的紀律，不是每個專案都要做到逐項——值得與可放寬的完整判準見 Prod Parity 原則 的判讀訊號段。這篇的 PHP 7.2 場景屬「值得」那一類：有原生擴充、MySQL 嚴格模式、時區邏輯都在，本機不對齊就會在線上才發現行為不同。

下一步

runtime 對齊好之後，你會想在 container 裡用順手的 shell 跟 editor——但那不能直接塞進這個 image，否則 image 就不再等於 prod。怎麼把 ergonomics 帶進來又不污染 parity，見 dotfile 跨進 runtime container。

ergonomics 進可寫層，不進 image

最容易犯的錯是把 zsh、vim、個人 config 寫進 runtime 的 Dockerfile。一旦 ergonomics 進了 image，這個 image 就不再等於 prod——線上不會有你的 oh-my-zsh，parity 當場破功。判準很硬：

• runtime image 只裝 app 需要、prod 也有的套件（見 對齊 prod 的 runtime container）。
• ergonomics 裝進「已啟動的 container」：docker compose exec <service> bash 進去後才裝，或 docker compose cp 把檔案送進去（已啟動的 container 無法事後 mount，掛載只能在 compose / docker run 當下宣告）。它活在容器的可寫層、不進 image。

這條分層讓同一個 runtime image 既是「線上的忠實複製」又能「開發時很好用」，兩個需求不打架。

ergonomics 層自己也要可攜

runtime 的 base 是 Debian，但你的 dotfile 是照 Arch 或 macOS 寫的。ergonomics 安裝腳本要能在 Debian container 裡跑，靠的是 package manager detection——同一支腳本用 command -v apt-get / pacman / apk 分支，適配當下所在的環境。原理見 Package Manager 抽象層。

跟工作站的入口 detection 不同，container 內只裝少數幾個工具、不值得拆多檔，適合行內 detection：一支腳本內分支、共用同一份工具清單。dotfiles repo 的 runtimes/php72-mysql57/ergonomics/setup.sh 就是這個形態。

落地形態

裝套件那一步分 distro，config 部署完全共通：

• 裝工具：把 setup.sh 送進已啟動的 container 再跑——docker compose cp ergonomics/setup.sh php:/tmp/setup.sh && docker compose exec php bash /tmp/setup.sh，它偵測 package manager 裝 zsh/git/vim。
• 部署 config：dotfiles repo 送進去再 stow——docker compose cp ~/dotfiles php:/root/dotfiles && docker compose exec php bash -c 'cd /root/dotfiles && stow zsh git vim'。config 本身可攜、不分 distro（見 GNU Stow）。

這樣 config 只維護一份，跟工作站共用；container 內只多了「裝套件」那一層 distro 分支。

邊界

ergonomics 進可寫層的代價是「不持久」：container 重建就沒了，每次 docker exec 重來或寫成啟動時自動跑的腳本。這是刻意的取捨——為了保住 image 的 parity，換來 ergonomics 每次重建要重裝。想持久化 ergonomics 又不碰 runtime image，正解是走 devcontainer 那套（見 模組九：從個人到團隊），它把開發環境跟 runtime image 明確拆成兩個 image。