什麼是 Dotfile

Unix 系統用檔名開頭的 . 標記隱藏檔。shell 配置（.bashrc、.zshrc）、Git 設定（.gitconfig）、SSH 設定（.ssh/config）、以及 ~/.config/ 底下各種工具的配置目錄，都屬於這個範疇。這些檔案決定了你的工作環境怎麼運作：shell 的 prompt 長什麼樣、alias 有哪些、editor 用什麼 keymap、terminal 的配色方案、視窗管理器怎麼排列畫面。

「dotfile 管理」指的是把這些散落在家目錄各處的配置檔集中到一個 Git repo，建立版本歷史、可以跨機器同步、可以在新環境一鍵部署。跟手動備份的差異在於：備份是搬檔案，dotfile 管理是建立一套可重複執行的環境建構流程。

為什麼要管理 Dotfile

開發環境是累積出來的。今天加一個 alias、明天改一個 Git 設定、下週裝了一個 terminal 外掛調了字型。這些微調加起來就是「你順手的工作環境」，但因為都是零碎的小改動，很少有人會主動記錄。

問題在累積到一定程度後、環境需要重建的那一刻才會浮出來：

換機器。拿到新筆電，開始從零設定。裝完 shell、editor、terminal，發現少了一堆 alias 和 function，但想不起來之前到底加了哪些。花兩天勉強恢復到七八成，剩下的在未來幾週慢慢「撞到才發現少了」。

設備故障或遺失。公司配的筆電硬碟壞了。如果配置沒有外部副本，那台機器上所有的自訂設定（有些可能花了半年慢慢調出來的）全部歸零。復原速度直接取決於「你有沒有把配置存在機器以外的地方」。

在 VM 或容器裡重現環境。想在虛擬機裡測試一套 Linux 桌面（例如 Hyprland），或在 Docker 容器裡重現自己的 shell 環境做 CI 除錯。沒有版控的配置，就得手動複製貼上，還要記住哪些檔案在哪個路徑。

跨機器一致性。同時用筆電、桌機、遠端伺服器，希望每台機器的 shell 行為、Git 設定、editor 快捷鍵都一致。手動同步的成本隨機器數量線性增長，而且很容易漏改某一台，導致操作習慣在不同機器間不一致。

這些場景的共通點是：配置的價值在累積，但累積的前提是有記錄。沒有記錄的累積，只是暫存在某一台機器上的隱性知識，機器一換就歸零。

哪些東西應該建立 Dotfile

依配置的普遍性和適用場景，分成三層來判斷：

核心層：幾乎所有開發者都該管的

• Shell 配置（.zshrc / .bashrc）：alias、function、PATH、prompt、completion 設定。這是最高頻修改、也最容易累積隱性知識的地方。
• Git 配置（.gitconfig）：使用者名稱、email、預設 editor、alias（git lg = git log --oneline --graph）、diff/merge tool。
• SSH 配置（.ssh/config）：Host 別名、ProxyJump 跳板設定、每台主機的 IdentityFile 指定。注意：config 檔進 repo，私鑰不進 repo。
• Editor 配置：.vimrc（Vim）、~/.config/nvim/（Neovim）、VS Code 的 settings.json / keybindings.json。

工具層：依個人工具鏈而定

• Terminal multiplexer：tmux（.tmux.conf）、zellij（~/.config/zellij/）的面板配置、快捷鍵、狀態列。
• Terminal emulator：Alacritty、WezTerm、Kitty 的字型、配色、快捷鍵設定。
• 套件清單：macOS 的 Brewfile（brew bundle dump）、Arch 的 pacman -Qqe > pkglist.txt。這份清單讓新機器知道該裝哪些軟體。
• 開發工具的全域配置：.npmrc、.cargo/config.toml、.pypirc 等。但要注意區分：.eslintrc / .prettierrc 這類通常跟著專案 repo 走（每個專案可能規則不同），不跟著人走。

桌面層：Linux 桌面環境才需要

• Window manager：Hyprland（~/.config/hypr/）、i3（~/.config/i3/）、sway 的配置。
• 桌面元件：狀態列（waybar）、應用程式啟動器（rofi / wofi）、通知服務（mako / dunst）、鎖屏（swaylock / hyprlock）。
• 主題與配色：GTK / Qt 主題設定、游標主題、字型配置。

判讀準則

區分一個配置該不該進 dotfile repo，核心問題是：這個設定是跟著人走，還是跟著專案走？

跟著人走的（不管開哪個專案都要用的）→ 進 dotfile repo。跟著專案走的（專案 A 用 ESLint、專案 B 用 Biome）→ 留在專案 repo。

不該進 Dotfile Repo 的

• 私鑰、API key、token、密碼。用 .gitignore 排除，敏感資訊放 secret manager 或加密管理（具體做法見同步與 Secret 管理）。
• 暫存檔、cache、log。.zsh_history 很大且含敏感指令；各種工具的 cache 目錄是 generated 檔案，重建時自動產生。
• OS 層級的二進位設定。macOS 的 plist 可以選擇性管理（defaults write 指令可以版控），但整個 ~/Library/Preferences/ 不適合直接丟進 Git——檔案格式不穩定、diff 不可讀、很多是應用程式自動產生的。

共用的核心原則

• 宣告式：描述「環境應該長什麼樣」，而非「操作了哪些步驟」。Terraform 宣告「要有一個 VPC、CIDR 是 10.0.0.0/16」；dotfile 宣告「zsh 的 prompt 格式是這樣、alias ll 對應 ls -la」。
• 版控下的變更歷史：誰改了什麼、什麼時候改的、為什麼改，都在 Git log 裡。環境出問題時可以回溯到「上一次正常的狀態」是哪個 commit。
• 可 review：改了一個 shell function，diff 清楚可讀。跟在 terminal 裡直接 export 一個變數、下次重開就忘了相比，版控下的改動有跡可循。

差異

這個平行不只是比喻。從個人到團隊會教怎麼把 dotfile 的思想正式擴展到團隊環境——devcontainer 把「開發環境應該長什麼樣」寫成宣告式配置，讓新人 clone repo 就能拿到一致的開發環境，這正是 IaC 思想從組織 infra 往個人工作桌面延伸的具體產物。

Dotfile 是重建指令，不是備份

這是最重要的心智模型區分。Dotfile repo 的目標不是「把舊電腦的所有檔案搬到新電腦」（那是備份工具的工作），而是「一份能在空白機器上重建工作環境的指令集」。

這個思維跟 Docker 的哲學一致：Docker image 透過 Dockerfile「描述如何重建」環境，而不是「對一台跑著的伺服器拍快照」。Dotfile repo 也是——它記錄的是「你的環境應該長什麼樣」的宣告，不是「你的機器上現在有什麼」的快照。

這個區分決定了 repo 裡該放什麼：

• 放進去的：宣告式的配置檔（shell config、editor config、WM config）、套件清單（Brewfile、pacman list）、安裝腳本（install.sh，用來在新機器上自動化部署流程）。
• 不放的：暫存狀態（shell history、undo file、session file）、generated 產物（plugin 的 compiled cache）、大型二進位檔（字型檔案可以用套件管理器裝，不用放 repo）。

維持「重建指令」的純度，repo 才能保持輕量、diff 可讀、跨機器部署不會帶進不必要的狀態。

SSH key 是典型例子：管理工具和 shell 配置的知識在模組一和模組二，但實際操作時 SSH key 比這兩者都早——因為 git clone git@github.com:... 本身就需要 SSH key。如果照模組順序走，到模組二才發現 dotfile repo clone 不下來。

這篇是路線圖，告訴你每一步做什麼、為什麼這個順序、以及去哪個模組看具體操作。

階段一：基礎設施（後續所有步驟的前提）

這些步驟在任何配置之前完成，因為它們是 Git、遠端存取、dotfile clone 的前提。

1. 安裝作業系統 + 建立使用者帳號

macOS：開箱即用。Linux：選發行版（Arch 如果要用 Hyprland）、完成安裝、建立非 root 使用者。安裝程式每個選項該怎麼判讀、裝完最小系統缺哪些必要工具（連 sudo 都可能沒有），見 Linux 安裝選項判讀 與 最小安裝後的工具驗證與補足——這一步是整個系列展開最深、卻最常被一句帶過的地基。

2. 生成 SSH key pair

1ssh-keygen -t ed25519 -C "your-email@example.com"

為什麼這麼早做：

• Git 操作：GitHub / GitLab 的 SSH 認證需要 public key。dotfile repo 通常用 SSH URL（git@github.com:...），clone 前要先把 key 部署到 GitHub。用 HTTPS URL 可以繞過 SSH key，但長期來看 SSH key 是更省事的認證方式。還沒有 key、或想用 HTTPS / PAT 把 dotfile 弄進一台新機器的幾種路徑，見 外部連入、SSH key 與無 key 的 bootstrap 路徑。
• 遠端救援：模組七的場景三（GPU hang）依賴 SSH 作為桌面凍結時的救生通道。key 提前設好，出問題時才有路可走。
• 跨機器操作：筆電連桌機、桌機連 VM、VS Code Remote SSH——都靠這把 key。

3. 部署 public key

把 ~/.ssh/id_ed25519.pub 加到需要的服務：

1# 加到 GitHub
2cat ~/.ssh/id_ed25519.pub
3# 複製輸出，貼到 GitHub → Settings → SSH and GPG keys → New SSH key
4
5# 加到另一台機器（可選，用於跨機器 SSH）
6ssh-copy-id user@target-machine

4. Package manager + Git

macOS：先裝 Homebrew（macOS 的套件管理器，後續安裝 stow、tmux 等工具都靠它），再裝 Git：

1# 安裝 Homebrew
2/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3
4# 安裝 Git（或用 xcode-select --install，會一併裝 Apple 的 Git）
5brew install git

Arch：pacman 隨 OS 安裝已可用，直接裝 Git：pacman -S git。

5. Clone dotfile repo

1git clone git@github.com:yourname/dotfiles.git ~/dotfiles

如果是第一次建 dotfile repo（還沒有 repo），先建一個空的再開始往裡面加配置。具體做法見模組一：管理工具與目錄結構。

階段二：Shell 與終端機（日常操作的基礎）

Shell 是所有操作的介面，終端機是 shell 的容器。這兩層配置好，後續的安裝、設定、除錯效率會高很多。

6. 安裝管理工具（stow / chezmoi）

把 dotfile repo 裡的配置 symlink 到正確位置。具體選型和操作見模組一。

7. Shell 配置（.zshrc / .bashrc）

模組化拆分、PATH 設定、alias、prompt。做完這一步，終端機操作才順手。見模組二：Shell 配置。

8. 終端機 + 編輯器

Terminal emulator 選型、tmux/zellij、neovim 基礎配置。見模組三：終端機與編輯器。

macOS 用戶到階段二完成後就有一個完整的工作環境。下一步依序讀模組一（管理工具選型）、模組二（shell 配置）、模組三（終端機），然後跳到階段四的 bootstrap script。階段三是 Linux 桌面環境的設定，macOS 用戶跳過。

階段三：桌面環境（Linux 限定）

macOS 用戶到階段二就有一個完整的工作環境了。以下步驟是 Linux 桌面環境的設定，macOS 用戶可以跳到階段四。

9. 視窗管理器

平鋪式 vs 浮動式的選型，Hyprland 安裝和核心配置。見模組四和模組五。

10. 桌面配套工具 + Rice

waybar、wofi、mako、配色系統。見模組六：桌面 Rice 設計。

11. 啟用 SSH server + 預防措施

桌面環境可用之後，設定遠端救援通道和預防性配置：

 1# SSH server（出問題時可以從另一台機器救援）
 2sudo systemctl enable sshd
 3sudo systemctl start sshd
 4
 5# 停用密碼登入（確保 SSH key 已設好）
 6# 編輯 /etc/ssh/sshd_config：PasswordAuthentication no
 7
 8# swap（OOM 緩衝）
 9sudo fallocate -l 4G /swapfile
10sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
11
12# systemd-oomd
13sudo systemctl enable systemd-oomd

為什麼放在桌面設定之後：SSH server 和 swap 是預防措施，桌面能用了才有東西要保護。但 SSH key pair（階段一步驟 2-3）要提前做——key pair 是認證基礎設施，server 只是把門打開。

詳細的故障場景和預防措施見模組七：桌面環境維護與故障排除。

階段四：同步與可攜性

環境建好之後，確保這份配置能搬到下一台機器。

12. Bootstrap script

把階段一到三的操作自動化成 script，下次換機器跑一次就好。見模組八：同步、Bootstrap 與環境重建。

13. Secret 管理

哪些東西該進 repo、哪些要排除（SSH private key、API token、密碼）。同樣見模組八。

依賴關係速查

 1OS 安裝
 2  └─ SSH key pair ← 後續所有 Git / SSH 操作的前提
 3       └─ Git 安裝
 4            └─ dotfile repo clone
 5                 └─ 管理工具（stow link）
 6                      ├─ Shell 配置
 7                      ├─ 終端機 + 編輯器
 8                      └─ 桌面環境（Linux，macOS 到此為止 → 直接跳階段四）
 9                           └─ SSH server + 預防措施
10                                └─ Bootstrap script 自動化

可以亂序的步驟

依賴圖裡同一層級的步驟可以調換順序。具體來說：

• Shell 配置、終端機配置、編輯器配置三者互不依賴，先做哪個都行
• 視窗管理器和桌面配套工具可以交替設定（先裝 Hyprland 再裝 waybar，或反過來）
• swap 和 SSH server 互不依賴，先做哪個都行

跨層級的依賴必須按順序：SSH key 是 clone repo 的前提，repo 是 stow link 的前提，stow link 是 shell 配置生效的前提。