成為 root：su -

su - 讓你從一般使用者切換成 root（系統管理員），整個 session 都以 root 身分操作。這個系列用到它，是因為在還沒有 sudo 的最小系統上，要裝 sudo、改系統設定，得先成為 root——而成為 root 的方式就是 su -，輸入 root 密碼後進入 root 的 shell。

那個 - 決定你載入哪一套環境。su - 啟動一個 login shell（模擬從頭登入、會跑完整的登入環境初始化），載入 root 自己的完整環境——把 PATH（shell 搜尋指令的目錄清單）換成 root 的（會包含 /usr/sbin 這類放管理工具的目錄）、工作目錄切到 root 的家。su（不加 -）則不啟動 login shell，環境多半沿用你呼叫時的、可能少掉那些管理工具目錄，於是有些管理指令會因為不在 PATH 裡而「找不到」，明明你已經是 root。所以要做系統管理，習慣用 su -。

su - 跟 sudo 解決的是不同情境。sudo 是「以 root 身分跑單一一條指令」，跑完就回到你自己；su - 是「整段都當 root」。這個系列先用 su - 是因為 sudo 還沒裝——一旦 sudo 裝好、wheel 群組（慣例上被授權可用 sudo 的群組）的授權設好，後面就改用 sudo <指令>，不再整段切 root。做完 root 的事，打 exit 回到原本的使用者。

用 nano 改設定檔

nano 是一個對照 vi 更直覺的文字編輯器，安裝過程改 locale.gen、hostname、sudoers 這些設定檔時會用到它。它的好處是所有快捷鍵都列在畫面最下面兩行，不必背。

那兩行裡的 ^ 符號代表 Ctrl 鍵。^O 就是 Ctrl+O、^X 就是 Ctrl+X。這個系列用到的幾個：

把這幾個串起來就是一次典型的設定檔編輯。以這個系列裡「解開 locale.gen 某一行的註解」為例：按 Ctrl+W 搜 en_US.UTF-8 UTF-8 跳到那行、用 Backspace 刪掉行首的 #、按 Ctrl+O 再 Enter 存檔、按 Ctrl+X 離開。改 hostname 則是 Ctrl+K 剪掉預設那行、打上新主機名、Ctrl+O、Ctrl+X。Ctrl+K 加 Ctrl+U 合起來就是「剪下再貼上」，是搬移整行的常見組合。

檔名與指令的大小寫

Linux 把大小寫當成不同的字元，這對檔名跟指令都成立。Setup 跟 setup 是兩個不同的東西、Documents 跟 documents 是兩個不同的資料夾、打 Sudo 不會執行到 sudo。這條規則貫穿整個系列：執行 archboot 的安裝程式是 setup（全小寫），啟動 Hyprland 桌面的指令是 Hyprland（首字母大寫），兩者差一個字母的大小寫就是不同的目標。

這對從 macOS 或 Windows 過來的人尤其常見，因為那兩個系統的預設檔案系統不分大小寫——在 Mac 上 File.txt 跟 file.txt 指向同一個檔，到了 Linux 就是兩個檔。同一個專案在 Mac 上跑得好好的，搬到 Linux 卻出現「檔案找不到」，常常就是某處大小寫對不上、而 Mac 的不分大小寫把問題藏了起來。

判讀方式很簡單：在 Linux 上，指令、檔名、路徑一律照原樣的大小寫打。錯誤訊息 command not found 或 No such file or directory 在你確定東西明明就在時，先懷疑大小寫。

shell 的幾個符號

這個系列的指令裡出現了幾個 shell 符號，它們是 shell 本身的語法、不是某個程式的參數，認得它們才讀得懂那些指令在做什麼。

> 跟 >> 是重導向，把本來會印到畫面的輸出改寫進檔案。> 覆蓋、>> 追加。系列裡 echo '%wheel ALL=(ALL:ALL) ALL' > /etc/sudoers.d/10-wheel 就是把那行文字寫進一個新檔，而設 authorized_keys 時用 >> 是為了追加、不洗掉既有的 key。

|（管線）把左邊指令的輸出，直接餵給右邊指令當輸入。傳 dotfile 進 VM 的 tar czf - . | ssh host 'tar xzf -' 就是把 tar 打包的資料流，不落地直接透過 ssh 送到對面解開。

&& 串接兩條指令，而且只有左邊成功才跑右邊。cd ~/dotfiles && ./scripts/install.sh 的意思是「先切到目錄，切成功了才跑腳本」——如果目錄不存在、cd 失敗，後面的腳本就不會在錯的目錄下執行。

$(...) 是命令替換，把括號裡指令的輸出，當成值填進當下這條指令。chsh -s "$(command -v zsh)" 會先跑 command -v zsh 得到 /usr/bin/zsh，再把這個路徑填給 chsh。理解這個語法，也才看得懂 工具驗證篇 講的 which 地雷：當 which 不存在、$(which zsh) 算出空字串，整條指令就拿到一個空值。

跟重導向相關的還有一個經典陷阱：sudo echo '內容' > /etc/某個-root-檔 會失敗。原因是重導向 > 由你的 shell 以你的身分執行，不是被 sudo 提權的那條指令——被提權的只有 echo，真正寫檔的還是你，而你沒權限寫那個 root 檔。解法是 echo '內容' | sudo tee /etc/某個-root-檔：tee 把流進它的 stdin 寫進檔案，而 tee 才是被 sudo 提權的那支，所以寫得進去。這個系列補 sudoers 檔時用的就是這個寫法。

權限對某些檔是硬要求，所以系列裡出現了 chmod。chmod 改檔案權限，那串數字是八進位的權限碼，三位分別代表擁有者/群組/其他人；每一位是讀（4）+ 寫（2）+ 執行（1）的和，所以 7 是全權、6 是可讀寫、4 是只讀、0 是無權。系列裡的 chmod 440（擁有者與群組可讀、其他人無權，給 sudoers 檔）、chmod 600（只有擁有者可讀寫，給私鑰）、chmod 700（只有擁有者全權，給 .ssh 目錄）就是這樣算出來的。這些檔對權限有要求——sudoers 必須是 440、私鑰必須只有自己讀得到，否則對應的工具會拒絕使用它們，所以那幾個 chmod 不是裝飾、是讓 sudo 跟 ssh 願意接受那些檔的條件。

下一步

認得這些基礎操作之後，就可以從 安裝選項判讀 開始走完整的安裝流程，過程中再遇到這幾個操作就不會卡。

本文用「桌面環境」泛指使用者看到的圖形介面整體。技術上，Hyprland 是 Wayland compositor——負責視窗合成和輸入管理，不含完整桌面環境（DE）的套件管理、設定面板等元件。GNOME、KDE Plasma 才是完整的 DE。但在故障隔離的討論中，關鍵區分是 kernel space vs userspace，compositor 和 DE 都在 userspace 這一側。

Kernel 與 Userspace 的隔離邊界

作業系統分成兩個執行空間。Kernel space 負責硬體驅動、記憶體管理、process 排程這些基礎設施。Userspace 跑所有應用程式，包括桌面環境本身。

兩個空間之間有硬體層級的隔離——CPU 的保護環機制（ring 0 是核心層級、ring 3 是應用程式層級，硬體強制限制 ring 3 的程式碼存取 ring 0 的記憶體）。Userspace 的 process 不管怎麼崩潰，都不會直接影響 kernel。Kernel 會清理掉崩潰的 process、回收它佔用的記憶體，然後繼續運作。

這個隔離機制解釋了一個關鍵差異：為什麼 Linux 上一個 app crash 通常只是那個視窗消失，而不會拖垮整台機器。

為什麼 Windows 會藍屏

Windows 的藍屏（Blue Screen of Death, BSOD）是 kernel panic 的表現——作業系統核心本身遇到無法恢復的錯誤，只能停機。

Windows 藍屏頻率較高的結構性原因在於顯示驅動的執行位置。Windows 把 GPU 驅動放在 kernel mode（WDDM 架構），NVIDIA 或 AMD 的驅動程式碼直接跑在核心空間。驅動有 bug 時，錯誤發生在 kernel space，清理掉再繼續的選項不存在——繼續執行可能造成資料損壞，只能停機。

藍屏頻率高是架構選擇的代價。把驅動放在 kernel mode 可以減少 context switch 的效能開銷，GPU 效能更好。代價是驅動 bug 的爆炸半徑從「app crash」升級成「整台停機」。Windows 10/11 已加入 TDR（Timeout Detection and Recovery）機制——GPU driver hang 時系統嘗試 reset driver 而非直接藍屏，大幅降低了 GPU 導致的 BSOD 頻率。但架構上 driver 仍在 kernel mode，藍屏的可能性仍然存在。

Linux 桌面的架構差異

Linux 桌面環境的顯示合成器（Hyprland、Sway、KDE Plasma 的 KWin）跑在 userspace。它們透過 DRM/KMS（Direct Rendering Manager / Kernel Mode Setting，Linux 的顯示子系統介面）跟 kernel 的 GPU 驅動溝通，但合成器本身的程式碼不在 kernel space 裡。

這個架構選擇的效果：

Compositor crash。Hyprland 如果遇到 segfault 或其他 fatal error，kernel 終止這個 userspace process。所有由它管理的視窗消失，螢幕回到 TTY 登入畫面或黑屏。但 kernel 還在跑——其他 TTY 可以登入，SSH 可以連線，背景的 service 繼續運作。

GPU driver bug。Linux 的 GPU 驅動分兩層：kernel module（可動態載入的核心擴充模組，如 nvidia.ko、amdgpu.ko）負責硬體操作，userspace 的 Mesa / NVIDIA userspace driver 負責 OpenGL/Vulkan 實作。Kernel module 出問題理論上可以 kernel panic，但實際行為取決於驅動。AMD 的開源 amdgpu 通常會嘗試 reset GPU 而非直接 panic，常見的表現是畫面凍結幾秒後恢復。NVIDIA 的閉源 nvidia.ko 是隔離模型的主要例外——kernel 社群無法審查或修復其程式碼，hang 時恢復能力遠弱於 amdgpu，經常拖垮整個 session 且 TTY 切換也受影響。這是後續故障場景中 NVIDIA 相關 caveat 的根源。

應用程式 crash。Firefox、VS Code、任何 GUI 程式崩潰，只有那個視窗消失。Compositor 繼續管理剩下的視窗，桌面環境不受影響。

TTY：kernel 存活時的首選救生通道

TTY（TeleTYpewriter）是 Linux 核心直接提供的純文字終端機介面，獨立於任何桌面環境。systemd 預設配置下有 6 個 virtual console（TTY1-TTY6）。Wayland compositor（如 Hyprland）通常佔用 TTY1，其餘可用。

切換方式：Ctrl+Alt+F2（切到 TTY2）到 Ctrl+Alt+F6（切到 TTY6）。

TTY 的重要性在於它不依賴 compositor。Hyprland 掛了、compositor crash 導致桌面消失——只要 kernel 還活著、GPU driver 仍能處理 VT switch，TTY 就能切過去登入操作：

• 用 htop 或 ps 查看哪個 process 出問題
• kill 有問題的 process
• 用 vim 或 nano 修改配置檔
• 重新啟動 Hyprland（Hyprland 指令）
• 如果需要，正常 reboot

TTY 切換失效的情境有兩種：kernel panic（極罕見）和 GPU 完全 hang 導致 VT switch 本身卡住（NVIDIA 閉源驅動在 Wayland 上較常見，需確保 nvidia_drm.modeset=1）。後者的替代手段是 SSH 遠端登入或 Magic SysRq 鍵（見常見故障場景的場景三）。

記憶體耗盡（OOM）的處理機制

Linux kernel 有 OOM Killer（Out of Memory Killer）機制——當記憶體和 swap 都用完、kernel 無法再分配新頁面時，自動挑選佔用記憶體最多、重要性最低的 process 強制終止，釋放記憶體讓系統繼續運作。

OOM Killer 的行為有時超出使用者的預期——它可能直接終止 Hyprland（因為 compositor 通常佔用不少記憶體），導致桌面突然消失。但關鍵是：系統沒有崩潰。Kernel 還在、TTY 還在、SSH 還在。

預防 OOM 的常見做法：

• 設定 swap（即使用 SSD，2-4GB 的 swap 也能在記憶體壓力大時提供緩衝）
• 啟用 systemd-oomd（userspace 的 OOM 管理，比 kernel OOM Killer 更早介入、更可控）
• 監控記憶體用量（btop 或 htop 可以看即時狀態）

故障層級速查

前五個層級都有恢復手段，只有 kernel panic 需要重開機。日常使用中遇到的故障多數落在前三層。

個人 Dotfile 跟團隊環境的邊界

兩者共用同一個核心思想（環境 as code、版控、可重現），但管理的對象和約定的範圍不同。個人 dotfile 是「我喜歡怎麼工作」，團隊環境是「這個專案需要什麼才能跑」。

Devcontainer：容器化的開發環境

Devcontainer 是微軟提出的開放規格（devcontainers.org），定義了怎麼用 Docker 容器作為開發環境。VS Code、GitHub Codespaces、JetBrains 都支援。

核心概念

專案 repo 裡放一個 .devcontainer/devcontainer.json，描述這個專案的開發環境需要什麼：

 1{
 2    "name": "My Project",
 3    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
 4    "features": {
 5        "ghcr.io/devcontainers/features/go:1": {
 6            "version": "1.22"
 7        },
 8        "ghcr.io/devcontainers/features/node:1": {
 9            "version": "20"
10        }
11    },
12    "postCreateCommand": "go mod download && npm install",
13    "customizations": {
14        "vscode": {
15            "extensions": [
16                "golang.go",
17                "esbenp.prettier-vscode"
18            ]
19        }
20    },
21    "forwardPorts": [8080, 3000]
22}

打開專案時，IDE 自動啟動這個容器、在裡面安裝指定版本的 Go 和 Node、跑 dependency install、裝 VS Code extension。新人 clone repo → 打開 → 等容器建好 → 直接開始寫 code。

跟個人 Dotfile 的互動

Devcontainer 管的是「專案需要什麼」，但你在容器裡工作時還是會想要自己的 shell alias、Git 設定、editor keybind。兩者的整合方式：

• dotfiles repo 自動部署：devcontainer.json 支援 "dotfiles.repository" 欄位，容器啟動時自動 clone 你的 dotfile repo 並執行 install script
• 個人 vs 團隊設定分離：.devcontainer/ 裡放團隊共用的環境定義，個人偏好透過 dotfiles 機制注入，不互相干擾

1{
2    "dotfiles.repository": "https://github.com/you/dotfiles",
3    "dotfiles.installCommand": "scripts/install.sh",
4    "dotfiles.targetPath": "~/dotfiles"
5}

這是個人 dotfile 和團隊環境標準化最乾淨的接合點——團隊定義「環境長什麼樣」，個人 dotfile 定義「在這個環境裡我怎麼操作」。

Devcontainer 的限制

• Docker 是前提：團隊每個人的機器都要裝 Docker，macOS 上要跑 Docker Desktop 或 OrbStack
• GUI 應用不適合：devcontainer 定位是 headless 開發環境，不處理圖形桌面
• 效能折扣：檔案系統操作在 macOS 上的 Docker volume 有效能折扣（Linux 上幾乎沒差）
• 離線環境：建容器需要拉 image 和 feature，斷網環境要另外處理（見 Infra 斷網模組）

Nix：宣告式的環境管理

Nix 是另一條技術路線，用宣告式的方式描述整個開發環境，不依賴 Docker。

核心概念

Nix 的 flake.nix（或 shell.nix）宣告了開發環境需要哪些套件，nix develop 進入這個環境：

 1# flake.nix
 2{
 3  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
 4
 5  outputs = { nixpkgs, ... }:
 6    let
 7      pkgs = nixpkgs.legacyPackages.x86_64-linux;
 8    in {
 9      devShells.default = pkgs.mkShell {
10        packages = with pkgs; [
11          go_1_22
12          nodejs_20
13          postgresql_16
14          redis
15        ];
16        shellHook = ''
17          echo "Dev environment ready"
18        '';
19      };
20    };
21}

跟 Devcontainer 的差異：Nix 不用容器，直接在宿主機上建立隔離的環境（透過 Nix store 的路徑隔離）。優點是沒有 Docker 的效能折扣和額外層級；缺點是 Nix 的學習曲線陡峭、語法不直覺。

Home Manager：Nix 管理 Dotfile

Nix 生態裡的 Home Manager 可以用 Nix 語言宣告式地管理整個家目錄的配置——等於用 Nix 取代 stow/chezmoi 做 dotfile 管理：

 1# home.nix
 2{ config, pkgs, ... }:
 3{
 4  programs.git = {
 5    enable = true;
 6    userName = "Your Name";
 7    userEmail = "you@example.com";
 8    extraConfig = {
 9      init.defaultBranch = "main";
10      pull.rebase = true;
11    };
12  };
13
14  programs.zsh = {
15    enable = true;
16    shellAliases = {
17      ll = "ls -alF";
18      gs = "git status";
19    };
20  };
21
22  programs.neovim = {
23    enable = true;
24    defaultEditor = true;
25  };
26}

Home Manager 把「安裝軟體」和「寫配置」統一成一份宣告——改完 home-manager switch 就同時更新套件和配置。這是 dotfile 管理的極致形式，但代價是整個技術棧鎖定在 Nix 生態裡。

核心套件

1sudo pacman -S hyprland xorg-xwayland xdg-desktop-portal-hyprland

[VM 可測試] 套件安裝本身在 VM 和實機上完全相同。

GPU 驅動

GPU 驅動決定 Hyprland 的渲染是走硬體加速還是軟體 fallback。AMD 和 Intel 開箱即用，NVIDIA 需要額外配置。

AMD（推薦，開箱即用）

1sudo pacman -S mesa vulkan-radeon libva-mesa-driver mesa-vdpau

mkinitcpio MODULES 加入：amdgpu

環境變數（放在 Hyprland 配置裡）：

1env = {
2    "LIBVA_DRIVER_NAME, radeonsi",
3    "VDPAU_DRIVER, radeonsi",
4    "AMD_VULKAN_ICD, RADV",
5}

AMD 是 Hyprland / Wayland 生態支援最好的 GPU。如果是新購硬體、有選擇的餘地，AMD 是最省事的選項。

Intel（開箱即用）

1sudo pacman -S mesa vulkan-intel intel-media-driver

mkinitcpio MODULES 加入：i915

1env = {
2    "LIBVA_DRIVER_NAME, iHD",
3    "VDPAU_DRIVER, va_gl",
4}

Intel 內顯在 Wayland 上表現穩定，適合筆電和輕度桌面使用。

NVIDIA（需要額外配置，非官方支援）

[需實機測試] NVIDIA 的所有設定在 VM 中無意義——VM 使用 virtio-gpu 或軟體渲染，不走 NVIDIA 驅動。以下步驟只在實體機有 NVIDIA 顯卡時才需要。

Hyprland 官方不支援 NVIDIA，但社群有成熟的 workaround。最低版本需求：

• NVIDIA driver >= 555（555 引入完整 GBM 支援和 explicit sync，是 Wayland 硬體渲染的最低依賴。535 系列有 explicit sync 問題，Wayland 下容易 flicker。590+ 修復多數 HDR 和多螢幕邊界問題）
• xorg-xwayland >= 24.1
• wayland-protocols >= 1.34

安裝：

1sudo pacman -S nvidia-dkms nvidia-utils libva-nvidia-driver
2# 32-bit 支援（遊戲可能需要）：
3sudo pacman -S lib32-nvidia-utils

mkinitcpio MODULES（依硬體配置選擇）：

純 NVIDIA 桌機：

1MODULES=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)

Intel + NVIDIA hybrid 筆電（Intel 排在 NVIDIA 前面）：

1MODULES=(i915 nvidia nvidia_modeset nvidia_uvm nvidia_drm)

更新 initramfs：

1sudo mkinitcpio -P

Modprobe 設定：

1# /etc/modprobe.d/nvidia.conf
2options nvidia_drm modeset=1

GRUB kernel parameter：

1# /etc/default/grub
2GRUB_CMDLINE_LINUX_DEFAULT="... nvidia_drm.modeset=1 nvidia_drm.fbdev=1"

更新 GRUB：

1sudo grub-mkconfig -o /boot/grub/grub.cfg

Hyprland 配置裡的 NVIDIA 環境變數：

1env = {
2    "LIBVA_DRIVER_NAME, nvidia",
3    "__GLX_VENDOR_LIBRARY_NAME, nvidia",
4    "GBM_BACKEND, nvidia-drm",         -- 如果 Firefox crash，移除這行
5    "NVD_BACKEND, direct",
6}

Cursor 修正（NVIDIA 常見的硬體 cursor 問題）：

1hl.config({
2    cursor = {
3        no_hardware_cursors = true,
4        allow_dumb_copy = true,
5    },
6})

Suspend/resume 支援：

1sudo systemctl enable nvidia-suspend.service nvidia-hibernate.service nvidia-resume.service

檢查 GPU 驅動狀態

1lspci -k | grep -A 3 VGA        # 查看使用中的驅動
2glxinfo | grep "OpenGL renderer" # 查看活躍的 renderer
3vulkaninfo --summary             # Vulkan 裝置資訊

GPU 驅動相關的故障診斷（driver hang、畫面凍結、suspend/resume 後異常）見桌面環境維護與故障排除。

桌面配套套件

Hyprland 只管視窗，以下是一個可用桌面需要的配套工具：

 1sudo pacman -S \
 2  kitty waybar wofi mako \
 3  polkit-gnome grim slurp wl-clipboard cliphist \
 4  hyprpaper hyprlock hypridle \
 5  pipewire pipewire-alsa pipewire-jack pipewire-pulse wireplumber \
 6  pamixer pavucontrol brightnessctl \
 7  bluez bluez-utils blueman \
 8  networkmanager network-manager-applet \
 9  thunar gvfs \
10  qt5-wayland qt6-wayland \
11  ttf-meslo-nerd noto-fonts noto-fonts-cjk

AUR 補充套件（用 yay 或 paru）：

1yay -S grimblast-git   # Hyprland 截圖 wrapper
2yay -S swww            # 動態桌布（hyprpaper 的替代）
3yay -S rofi-wayland    # 功能比 wofi 更豐富的 launcher

[已驗證] 套件安裝在 VM 中完全可執行。waybar、wofi、mako、hyprlock 在 virtio-gpu-gl-pci 加速下正常 render（Hyprland 0.55 + UTM 4.7.5 實測）。

[需實機測試] 藍牙（bluez）、亮度（brightnessctl）、音訊裝置偵測（pipewire）需要實際硬體。

登入管理器

Hyprland 預設不含登入管理器。三個選項：

從 TTY 直接啟動（最簡單）

登入文字介面後直接執行 Hyprland。建議用 wrapper script 設定必要的環境變數：

1#!/bin/sh
2# ~/start-hyprland.sh
3export XDG_SESSION_TYPE=wayland
4export XDG_CURRENT_DESKTOP=Hyprland
5export XDG_SESSION_DESKTOP=Hyprland
6exec Hyprland

1chmod +x ~/start-hyprland.sh
2~/start-hyprland.sh

greetd + tuigreet（推薦）

greetd 是一個輕量的登入管理器，tuigreet 是它的 TUI 前端：

1sudo pacman -S greetd greetd-tuigreet

設定 /etc/greetd/config.toml：

1[terminal]
2vt = 1
3
4[default_session]
5command = "tuigreet --cmd Hyprland"
6user = "greeter"

自動登入（可選）：

1[initial_session]
2command = "Hyprland"
3user = "yourusername"

啟用服務：

1sudo systemctl enable greetd

SDDM

如果已經有 KDE 或偏好圖形化登入介面：

1sudo pacman -S sddm
2sudo systemctl enable sddm

SDDM 會自動偵測到 Hyprland 並在登入畫面顯示它作為 session 選項。

[VM 可測試] 登入管理器的設定在 VM 中可完整測試。

首次啟動常見問題

配置格式：Lua 取代 hyprlang（v0.55+）

Hyprland v0.55（2026 年 4 月）起，配置格式從 hyprlang（.conf）遷移到 Lua（.lua）。舊的 hyprland.conf 在沒有 .lua 檔案時仍然可用，但 hyprlang 已被標記為 deprecated，預計在後續版本移除。

遷移工具：hyprlang2lua（Go，有瀏覽器版）、hyprconf2lua（Python pip）、hypr-migrate。

本系列後續文章（Hyprland 核心配置、Workspace 與外觀、Caelestia）都使用 Lua 格式。如果在網路上看到 .conf 格式的教學，多數仍然可用，但建議儘早遷移到 Lua。

拆分配置用 Lua 原生的 require()：

1-- hyprland.lua
2require("keybinds")    -- 載入同目錄下的 keybinds.lua
3require("rules")       -- 載入同目錄下的 rules.lua
4require("appearance")

詳細的配置語法和設定邏輯在核心配置和 Workspace、Window Rules 與外觀。

其他發行版

Fedora

Fedora 39 起即在官方 repo。安裝：

1sudo dnf install hyprland

JaKooLit 提供自動化安裝腳本（github.com/JaKooLit/Fedora-Hyprland），Fedora 42+ 運作良好。

NixOS

NixOS 有官方 module，在 configuration.nix 加入：

1programs.hyprland.enable = true;

Home Manager 也有對應 module，可以宣告式管理 Hyprland 配置。

Ubuntu

不推薦。Ubuntu 的 point-release 模型跟 Hyprland 的 bleeding-edge 更新節奏衝突。沒有官方 PPA，從 source 編譯可行但維護成本高。如果一定要用 Debian 系，Arch 的 rolling release 或 Fedora 的半年週期更適合 Hyprland。

安裝後的下一步

安裝完成後，VM 環境的額外設定（環境變數、效能調整、測試矩陣）見 VM 環境設定與測試矩陣。配置檔的組織方式和 keybind 設計見 Hyprland 核心配置。

Hyprland（v0.55+ 的配置格式）、Neovim（整個 plugin 和配置生態）、WezTerm（terminal emulator 配置）都用 Lua 作為配置語言。在 dotfile 管理的脈絡裡，Lua 是讀懂和寫好這些工具配置的前提知識。

配置檔用到的核心語法

變數和型別

1local name = "hello"       -- 字串
2local count = 42            -- 數字
3local enabled = true        -- 布林
4local nothing = nil         -- 空值（類似其他語言的 null）

local 宣告區域變數。沒有 local 的變數是全域的，配置檔裡幾乎都該用 local。

Table：唯一的複合資料結構

Lua 只有一種複合型別——table，同時當 array 和 dictionary 用：

 1-- 當 array（index 從 1 開始，不是 0）
 2local fruits = { "apple", "banana", "cherry" }
 3print(fruits[1])  -- "apple"
 4
 5-- 當 dictionary
 6local config = {
 7    gaps_in = 5,
 8    border_size = 2,
 9    layout = "dwindle",
10}
11print(config.gaps_in)  -- 5
12
13-- 巢狀 table（配置檔最常見的形式）
14local decoration = {
15    rounding = 8,
16    blur = {
17        enabled = true,
18        size = 5,
19        passes = 2,
20    },
21}

Hyprland 的 hl.config() 接收的就是一個巢狀 table：

1hl.config({
2    general = {
3        gaps_in = 5,
4        gaps_out = 10,
5    },
6    decoration = {
7        rounding = 8,
8    },
9})

Function

1local function greet(who)
2    return "hello " .. who   -- .. 是字串串接
3end
4
5-- 匿名 function（Neovim 配置常見）
6vim.keymap.set("n", "<leader>f", function()
7    require("telescope.builtin").find_files()
8end)

條件判斷

1if hostname == "work-laptop" then
2    -- 工作機設定
3elseif hostname == "home-desktop" then
4    -- 家裡桌機設定
5else
6    -- 預設
7end

只有 nil 和 false 是 falsy。0 和 "" 是 truthy（跟 Python 不同）。

迴圈

 1-- 數字 for（Hyprland 批次產生 workspace keybind）
 2for i = 1, 9 do
 3    hl.bind("SUPER", tostring(i), "workspace", tostring(i))
 4end
 5
 6-- 遍歷 table
 7local tools = { "zsh", "git", "nvim", "tmux" }
 8for _, tool in ipairs(tools) do
 9    print(tool)
10end

模組化（require）

1-- hyprland.lua 裡載入同目錄的其他 .lua 檔
2require("keybinds")     -- 載入 keybinds.lua
3require("rules")        -- 載入 rules.lua
4require("appearance")   -- 載入 appearance.lua

require() 是 Lua 原生的模組載入，取代了舊 Hyprland .conf 格式的 source = ... 指令。

為什麼配置工具選 Lua

Lua 被嵌入到配置層的原因是一組特定的 trade-off：

• 比 JSON/TOML/YAML 強：有變數、迴圈、條件判斷。配置檔可以用 for 產生重複項目、用 if 處理機器差異，不需要外部 template engine
• 比 Python/JavaScript 輕：300KB 的直譯器可以嵌入 C/C++ 程式，不需要拖一個完整的 runtime
• 沙盒化容易：宿主程式可以控制 Lua 能存取哪些 API，限制配置檔的能力範圍

這也是 Neovim 從 VimScript 遷移到 Lua 的理由——plugin 生態需要一個真正的程式語言（有資料結構、有錯誤處理），但又不能讓配置檔變成一個安全隱患。

其他使用 Lua 的場景

共同模式：一個用 C/C++ 寫的高效能核心，把 Lua 嵌入進去當配置和擴展語言。

跟 Python/JavaScript 的差異速查

寫 Hyprland 或 Neovim 配置用到的 Lua 知識量很小——主要是 table（配置結構）、for loop（批次 keybind）、if-else（機器差異）、require（模組拆分）。不需要學 metatable、coroutine、metatmethod 這些進階功能。

Dotfile 管理的判讀：配置格式是純文字（TOML/Lua/INI/JSON）的 terminal emulator，配置檔可以直接進 dotfile repo。iTerm2 這種以 GUI 面板為主的，要用它的匯出功能另外處理。

選型建議：如果跨 macOS + Linux 雙平台，Alacritty 或 WezTerm 的「一份配置兩邊通用」是明確優勢。如果只在 Linux 上用 Wayland，Foot 是輕量首選。

該放進配置的核心項目

• 字型：字型家族、大小、行高。建議使用 Nerd Font（含 icon glyph 的程式字型），很多 TUI 工具和 prompt 依賴這些 glyph
• 配色：前景/背景色、ANSI 16 色的定義。配色方案（Catppuccin、Tokyo Night、Gruvbox 等）通常有各 terminal 的預設配置檔可直接套用
• 快捷鍵：分頁/分割畫面的快捷鍵。注意跟 tmux/zellij 的快捷鍵衝突問題
• 渲染：GPU 加速、字型 hinting、抗鋸齒設定

配色系統的跨工具一致性

配色方案（color scheme）會同時影響 terminal emulator、editor、tmux status bar、shell prompt。用同一套配色方案（例如 Catppuccin Mocha）跨工具統一視覺是 rice 的基礎。

管理方式：

• 每個工具各自的配色設定檔都放進 dotfile repo
• 主題選擇集中記錄（例如 dotfile repo 的 README 寫「全域使用 Catppuccin Mocha」），換主題時有對照清單知道要改哪些檔案
• 部分配色方案提供「一鍵安裝腳本」涵蓋多個工具，也可以放在 bootstrap script 裡

字型管理

Nerd Font 是需要安裝在系統上的，不是單純的配置檔。處理方式：

• macOS：Brewfile 裡加 cask "font-hack-nerd-font"（透過 homebrew-cask-fonts tap）
• Linux：套件管理器安裝或手動下載到 ~/.local/share/fonts/
• 字型檔案本身不進 dotfile repo（太大、有版權），只記錄「安裝哪個字型」在套件清單或 bootstrap script 裡

安裝字型後如果畫面仍然顯示豆腐方塊，原因通常不是字型沒裝好，而是顯示它的程式在安裝之前就已啟動。每個 process 的可用字型集合在啟動時決定，之後新裝的字型對它不可見——需要重啟該程式才生效。詳見 字型的可用集合在 process 啟動時決定。fontconfig 的工具分工與 fallback 機制見 fontconfig。

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 確保不存在也不報錯。

拍照：VM 快照與磁碟映像

第一種是拍照。VM 快照和磁碟映像（Clonezilla、dd）做的事是把整台機器某一刻的完整狀態凍結存檔——整個虛擬硬碟的 block-level 複製，有時連記憶體狀態都包含。還原就是把映像寫回去，系統回到那一刻，像時光倒流。Docker 的 docker commit 也屬於這個方向：把正在跑的 container 的檔案系統快照成一個 image。

拍照產出的是黑盒子。一個磁碟映像是二進制檔案，沒人能看出裡面到底做了什麼設定、裝了什麼、改過什麼。它大（動輒 GB 級）、跟硬體耦合（換不同架構或不同顯卡可能開不起來）、無法做 diff 或 code review。

重建指令：Dotfile repo + install script

第二種是重建指令。Dotfile repo + install script 描述的是「怎麼從一台空白機器組出這個環境」，每次都從零開始執行。Dockerfile 也是重建指令——一份「照著做就能重現」的食譜，描述每一步該安裝什麼、複製什麼、怎麼啟動。

重建指令產出的是白盒子。每一步都是可讀的文字——這行裝 zsh、那行設定 Hyprland 的 keybind——可以被 review、被 diff、被另一個人讀懂。它小（通常幾十 KB）、跨硬體（同一份 script 加 OS 判斷就能跑在不同機器）、可以進版控走 PR 流程。

dotfile 管理選的是重建指令這條路。代價是你必須把環境建構的過程記錄清楚——每裝一個新工具、每改一個配置都要同步更新 repo。回報是任何一台機器、任何時間點，都能用一份 Git repo 重現你的工作環境。

場景判讀

兩者不互斥——常見的組合是：用 dotfile 管理配置（長期可維護的基線），VM 快照用於短期實驗保護（改爛了可以秒回）。

Caelestia 這類「desktop shell 專案」做的就是把上述元件統一設計、統一配色、統一出貨，省去自己一個個挑的功夫。它用的是 Quickshell（QML 框架）把所有元件包成一套風格一致的桌面。本模組教的是自己組裝的方式——理解各元件的配置，之後要用 Caelestia 或自己拼都能做。

Waybar：狀態列

Waybar 是 Hyprland 桌面最常用的狀態列。配置在 ~/.config/waybar/，分兩個檔案：config.jsonc（結構和模組）和 style.css（外觀）。

結構配置

 1// ~/.config/waybar/config.jsonc
 2{
 3    "layer": "top",
 4    "position": "top",
 5    "height": 36,
 6    "spacing": 4,
 7
 8    // 左中右三區塊各放哪些模組
 9    "modules-left": ["hyprland/workspaces", "hyprland/window"],
10    "modules-center": ["clock"],
11    "modules-right": ["pulseaudio", "network", "cpu", "memory", "battery", "tray"],
12
13    // 各模組設定
14    "hyprland/workspaces": {
15        "format": "{id}",
16        "on-click": "activate"
17    },
18    "clock": {
19        "format": "{:%H:%M}",
20        "format-alt": "{:%Y-%m-%d %H:%M}",
21        "tooltip-format": "<tt>{calendar}</tt>"
22    },
23    "battery": {
24        "format": "{capacity}% {icon}",
25        "format-icons": ["", "", "", "", ""],
26        "states": {
27            "warning": 30,
28            "critical": 15
29        }
30    },
31    "network": {
32        "format-wifi": "{essid} ({signalStrength}%)",
33        "format-ethernet": "{ifname}",
34        "format-disconnected": "Disconnected"
35    },
36    "pulseaudio": {
37        "format": "{volume}%",
38        "on-click": "pavucontrol"
39    }
40}

format 欄位裡的 icon 字元來自 Nerd Font——終端機與編輯器提到的字型安裝是這裡正常顯示的前提。

外觀 CSS

 1/* ~/.config/waybar/style.css */
 2
 3* {
 4    font-family: "MesloLGS Nerd Font", monospace;
 5    font-size: 13px;
 6}
 7
 8window#waybar {
 9    background-color: rgba(30, 30, 46, 0.85);
10    color: #cdd6f4;
11}
12
13#workspaces button {
14    padding: 0 8px;
15    color: #6c7086;
16    border-radius: 6px;
17}
18
19#workspaces button.active {
20    color: #cdd6f4;
21    background: rgba(137, 180, 250, 0.2);
22}
23
24#clock, #battery, #network, #pulseaudio {
25    padding: 0 10px;
26}
27
28#battery.warning {
29    color: #f9e2af;
30}
31
32#battery.critical {
33    color: #f38ba8;
34}

CSS 裡的色碼（#cdd6f4、#89b4fa、#f38ba8）來自配色方案（這個範例用的是 Catppuccin Mocha）。統一使用同一套色碼是 rice 視覺協調的基礎。

Config 裡的字族名必須跟系統實際安裝的字族逐字相符。Nerd Font 的圖示落在專屬碼位範圍，只有對應的那支字帶這些 glyph——指定一個沒裝的字族名，文字排版引擎找不到 glyph 就會顯示豆腐方塊。確認實裝字族名的方式：

1fc-list | grep -i meslo
2# MesloLGSNerdFont-Regular.ttf: "MesloLGS Nerd Font":style=Regular

引號內的字串是 config 該填的字族名。

同一份 Waybar config 能同時服務筆電、桌機與 VM，靠的是模組對缺少硬體的自動退化：battery 在沒有電池的機器直接隱藏該模組、不報錯也不留空位；pulseaudio 在沒有音訊服務時顯示為空；network 顯示當下實際在用的介面。不必為不同機器維護多份 config——把可能用到的模組都列上，用不到的那台自己消失。

Wofi / Rofi：啟動器

啟動器是按快捷鍵彈出的搜尋框，用來啟動應用程式、執行指令、搜尋檔案。

Wofi（Wayland 原生）配置：

1# ~/.config/wofi/config
2show=drun
3width=600
4height=400
5prompt=Search...
6insensitive=true
7allow_markup=true

 1/* ~/.config/wofi/style.css */
 2window {
 3    background-color: #1e1e2e;
 4    border: 2px solid #89b4fa;
 5    border-radius: 12px;
 6}
 7
 8#input {
 9    background-color: #313244;
10    color: #cdd6f4;
11    border-radius: 8px;
12    margin: 10px;
13    padding: 8px 12px;
14}
15
16#entry:selected {
17    background-color: rgba(137, 180, 250, 0.2);
18}

Rofi（需要 wayland fork rofi-lbonn-wayland）功能更豐富——支援多種 mode（drun、window、ssh、自定義 script）、主題系統更完整。如果需要進階功能（例如 emoji picker、密碼管理器整合），Rofi 是更好的選擇。

Mako / Dunst：通知

Mako 是 Wayland 原生的通知 daemon，負責顯示通知——它監聽 D-Bus 的 org.freedesktop.Notifications 介面、把收到的通知畫出來。產生通知的是應用程式，透過 libnotify 送上 D-Bus。所以一套能用的通知鏈需要兩半：daemon（顯示）和 libnotify（產生與遞送）。缺了 libnotify，連命令列自測用的 notify-send 都沒有。套件清單要同時列 mako 和 libnotify。

配置簡潔：

 1# ~/.config/mako/config
 2font=MesloLGS Nerd Font 11
 3background-color=#1e1e2e
 4text-color=#cdd6f4
 5border-color=#89b4fa
 6border-radius=8
 7border-size=2
 8padding=12
 9default-timeout=5000
10max-visible=3
11
12[urgency=critical]
13border-color=#f38ba8
14default-timeout=0

通知的視覺風格（圓角、配色、字型）要跟 waybar 和啟動器一致，這是整體 rice 不散的關鍵。

Nerd Font 的字符集只含 Latin、圖示與 Powerline 符號，不含中日韓。任何 CJK 文字（通知內文、視窗標題）若系統沒有 CJK 字型可 fallback 會變豆腐方塊。修法是安裝 CJK fallback（如 noto-fonts-cjk），fontconfig 會自動補字、不需改各工具的 config。另外，中途補裝字型後已在跑的 daemon 需重啟才看得到——reload 類指令只重讀設定檔、不重建記憶體中的字型快照（原理見 字型的可用集合在 process 啟動時決定）。

Grim + Slurp：截圖

Grim 負責截圖、Slurp 負責框選區域，兩者搭配使用。截圖結果透過 wl-copy 送進剪貼簿時，需要明確指定 MIME 型別：

1# 全螢幕截圖到剪貼簿
2grim - | wl-copy --type image/png
3
4# 框選區域截圖到剪貼簿
5grim -g "$(slurp)" - | wl-copy --type image/png
6
7# 全螢幕截圖存檔
8grim ~/screenshot.png

wl-copy 不帶 --type 時會嘗試透過 xdg-utils（xdg-mime）推斷 stdin 的型別。最小安裝環境沒有 xdg-utils 的情況下，PNG bytes 會被誤標成 text/plain，貼進影像應用程式就拿不到圖。明確帶 --type image/png 讓行為不依賴環境是否安裝了 xdg-utils。確認剪貼簿內容型別：

1wl-paste --list-types
2# 應顯示 image/png

Hyprland keybind 範例：

1bind = , Print, exec, grim - | wl-copy --type image/png
2bind = SHIFT, Print, exec, grim -g "$(slurp)" - | wl-copy --type image/png

浮動式（floating） 是多數人熟悉的模式。視窗可以重疊、可以任意拖拉調整大小、可以最小化藏起來。macOS、Windows、GNOME、KDE 預設都是浮動式。操作直覺是「每個視窗是一張紙，自己決定放哪裡」。

平鋪式（tiling） 的規則不同：視窗自動排列填滿螢幕、不重疊，由 WM 的規則決定版面怎麼切割。開一個新視窗時，WM 自動把現有空間分一半給它；關掉一個視窗時，相鄰視窗自動擴展填補。操作直覺是「螢幕是一塊蛋糕，WM 負責切」。

多數平鋪式 WM 支援混合模式：特定視窗可以設為浮動，脫離平鋪規則。設定面板、密碼輸入框、小工具這類不適合塞進格子的視窗，通常會設成浮動例外。平鋪是預設，浮動是按需啟用的例外。

手動貼齊 vs 自動平鋪

在進入平鋪式 WM 之前，macOS 和 Windows 都提供了「手動貼齊」功能——用快捷鍵或拖拉把視窗貼到螢幕的半邊、角落、三分之一。macOS 原生的 window snapping、Windows 的 Snap Layout、以及 Rectangle 和 Magnet 這類第三方工具都屬於這個範疇。

手動貼齊跟自動平鋪的差距，在視窗數量少的時候幾乎感覺不到。開兩個視窗、左右各半，手動按一下快捷鍵就到位，完全夠用。

差距在視窗數量多的時候才出現。每開一個新視窗都要決定它放哪、按對應的快捷鍵；關掉一個視窗就留下空洞，要手動拖拉其他視窗去填——當這種版面管理的決策負擔開始分散你對工作本身的注意力時，就是自動平鋪開始有價值的時機。這個斷點因螢幕大小和工作類型而異：23 吋單螢幕上同時開終端機、編輯器、瀏覽器、文件，版面很快就不夠分；雙螢幕寬螢幕上同樣的視窗數量可能還很從容。

自動平鋪在這個情境下的優勢有三層。

第一層是自動回填。開視窗、關視窗，WM 自動重新分配空間，版面永遠是滿的、整齊的。你不用做任何版面決策。

第二層是操作對象的轉換。手動貼齊的操作對象是「某個視窗」——把 A 視窗貼到左邊、把 B 視窗貼到右上。平鋪式 WM 的操作對象是「版面結構」——把焦點往右移、把當前視窗跟隔壁交換、把這一格再水平切一半。你操作的是位置關係，不是絕對座標。

第三層是工作區整合。平鋪式工作流通常搭配多個工作區（workspace），每個工作區是一套獨立的平鋪佈局。「編輯器和終端機在工作區 1、瀏覽器在工作區 2、通訊軟體在工作區 4」——用快捷鍵瞬間切換整套上下文，而不是在一堆重疊視窗裡找。手動貼齊工具通常不帶工作區管理。

適用判讀

平鋪式視窗管理的投資報酬率取決於你的工作型態。

高回報情境：經常同時操作多個視窗且版面管理開始分散注意力、多數是「方方正正、可平鋪」的 app（終端機、編輯器、瀏覽器、文件閱讀器）、鍵盤操作為主、多螢幕、工作需要頻繁切換上下文（多個專案、不同任務區）。

低回報情境：大量使用需要特定比例或自由拖拉的 app（設計工具、影片剪輯、簡報製作）、很少同時開多個視窗、已經習慣且滿意目前的工作流、不想花時間學新鍵位。

折衷方案：所有平鋪式工具都支援 per-app 的浮動例外。不適合平鋪的 app（設定面板、計算機、某些對話框）設成浮動，其餘維持平鋪。這不是全有全無的選擇。

一個常見的踩坑模式是：看到 Hyprland 的截圖很漂亮，衝動裝了，發現日常有一半 app 不適合平鋪、鍵位記不住、每次更新都要修配置，兩週後放棄。務實的進入路徑是先在目前的系統上試手動貼齊工具（macOS 的 Rectangle 或 AeroSpace），確認自己真的享受鍵盤操作視窗的節奏，再往 Linux tiling WM 推進。或者用 VM 跑 Hyprland 體驗看看——體驗打折（VM 沒有 GPU 加速，動畫會卡），但能確認自己是否喜歡這種操作邏輯，再決定要不要花時間在實體機上搭建。

Git bare repo：直接把家目錄當 work tree

bare repo 的概念是在家目錄建一個沒有工作目錄的 Git 倉庫，然後用 alias 指定 --work-tree=$HOME，讓 Git 直接追蹤家目錄下的檔案，不需要 symlink、不需要額外工具。

初始化：

1git init --bare "$HOME/.dotfiles"

在 shell 配置裡加一行 alias：

1alias dotfiles='git --git-dir="$HOME/.dotfiles" --work-tree="$HOME"'

之後所有 dotfile 操作都透過這個 alias：

1dotfiles add ~/.zshrc
2dotfiles commit -m "add zshrc"
3dotfiles remote add origin git@github.com:you/dotfiles.git
4dotfiles push -u origin main

第一件要做的事是隱藏未追蹤檔案。家目錄底下有成千上萬個檔案，如果不設定這一行，dotfiles status 會列出所有未追蹤的東西：

1dotfiles config --local status.showUntrackedFiles no

新機器還原的流程：

1git clone --bare git@github.com:you/dotfiles.git "$HOME/.dotfiles"
2alias dotfiles='git --git-dir="$HOME/.dotfiles" --work-tree="$HOME"'
3dotfiles config --local status.showUntrackedFiles no
4dotfiles checkout

checkout 這步會把 repo 裡的檔案寫到家目錄。如果家目錄已經有同名檔案（例如系統預設的 .bashrc），checkout 會失敗並列出衝突檔案，需要先手動備份或刪除。

bare repo 適合配置量少、只管一台機器、不想安裝任何額外工具的人。它的限制是：概念對 Git 初學者不直覺（bare repo + work-tree 的組合不常見）、沒有模組化的概念（無法選擇性安裝某些配置）、多 profile 支援弱（不同機器要不同配置時只能靠 branch，長期維護困難）。

GNU Stow：symlink 農場管理器

Stow 的概念是把 dotfile 集中放在一個普通目錄（如 ~/dotfiles），然後用 stow 指令在家目錄建立 symlink。stow 的核心規則是：package 目錄內的路徑結構，就是安裝後相對於目標目錄的路徑結構。

1# 安裝 stow
2# macOS
3brew install stow
4# Arch Linux
5sudo pacman -S stow
6# Ubuntu/Debian
7sudo apt install stow

以 zsh 配置為例，目錄結構長這樣：

1~/dotfiles/zsh/.zshrc

執行 stow zsh 後，stow 會在 $HOME 建一個 symlink：

1~/.zshrc -> ~/dotfiles/zsh/.zshrc

對於放在 ~/.config/ 底下的工具（XDG 規範），目錄結構映射同樣的邏輯：

1~/dotfiles/nvim/.config/nvim/init.lua
2~/dotfiles/nvim/.config/nvim/lua/plugins.lua

執行 stow nvim 後：

1~/.config/nvim -> ~/dotfiles/nvim/.config/nvim

stow 會自動判斷該 symlink 整個目錄還是個別檔案——如果目標目錄不存在或目錄內所有檔案都由同一個 package 管理，stow 會 symlink 整個目錄（folding）；如果目標目錄已有其他檔案，stow 會展開（unfolding）成逐檔 symlink。

初始化和日常操作：

 1# 初始化
 2mkdir ~/dotfiles && cd ~/dotfiles
 3git init
 4git remote add origin git@github.com:you/dotfiles.git
 5
 6# 把現有 .zshrc 搬進 dotfiles
 7mkdir -p ~/dotfiles/zsh
 8mv ~/.zshrc ~/dotfiles/zsh/.zshrc
 9cd ~/dotfiles && stow zsh
10# 現在 ~/.zshrc 是一個 symlink，指向 ~/dotfiles/zsh/.zshrc
11
12# 日常修改：直接編輯，symlink 透通
13vim ~/.zshrc  # 實際編輯的是 ~/dotfiles/zsh/.zshrc
14cd ~/dotfiles && git add -A && git commit -m "update zshrc"
15
16# 新機器還原
17git clone git@github.com:you/dotfiles.git ~/dotfiles
18cd ~/dotfiles && stow zsh git nvim tmux

批次安裝所有 package：

1cd ~/dotfiles
2# stow 會把每個頂層目錄當成一個 package
3stow */

移除某個 package 的 symlink：

1cd ~/dotfiles && stow -D nvim

stow 適合中等複雜度的配置管理。它的優勢是模組化（每個工具獨立一個 package、可選擇性安裝）和概念直覺（目錄結構就是安裝後的樣子）。它的限制是只管 symlink 映射，不管套件安裝；跨 OS 的路徑差異（macOS 和 Linux 某些工具的配置路徑不同）需要自己處理；stow 也不管 file permission——需要 0600 權限的 secret 檔（SSH private key、API token config）靠 symlink 繼承來源檔案權限，不能在部署過程中自動設定。

yadm：bare repo 的升級版

yadm 包裝了 Git bare repo 的操作，加上三個 bare repo 缺少的能力：alternate files（依 OS、hostname、甚至 user 條件選擇安裝不同版本的配置檔）、encrypt（用 GPG 或 OpenSSL 加密敏感檔案、不依賴外部密碼管理器）、bootstrap script（clone 後自動跑初始化）。

 1# 安裝
 2brew install yadm          # macOS
 3sudo pacman -S yadm        # Arch
 4
 5# 初始化（等同 git init --bare + 自動設定 alias）
 6yadm init
 7yadm remote add origin git@github.com:you/dotfiles.git
 8
 9# 操作方式跟 Git 完全一樣
10yadm add ~/.zshrc
11yadm commit -m "add zshrc"
12yadm push

Alternate files 的概念是在同一個 repo 裡放多個版本的同一個檔案，yadm 依條件決定用哪一個：

1~/.config/alacritty/alacritty.toml##os.Darwin
2~/.config/alacritty/alacritty.toml##os.Linux

macOS 上 yadm 自動 checkout Darwin 版本、Linux 上 checkout Linux 版本。比 stow 的 shell if-else 判斷更乾淨，比 chezmoi 的 Go template 學習曲線低。

yadm 適合想要 bare repo 的簡單性、但需要條件安裝或 secret 加密的人。它的限制是沒有 stow 的模組化概念（無法選擇性只安裝某些工具的配置）、沒有 chezmoi 的 template 細粒度（alternate files 是整個檔案切換，不是檔案內的段落條件）。

Chezmoi：多機器 dotfile 管理工具

Chezmoi 是專為 dotfile 管理設計的工具，原生處理 template、secret 管理和多機器差異。它把 dotfile 存在自己的 source directory（~/.local/share/chezmoi），用 chezmoi apply 把檔案實際寫入目標位置（不是 symlink，是複製）。

1# 安裝
2brew install chezmoi        # macOS
3pacman -S chezmoi           # Arch
4sh -c "$(curl -fsLS get.chezmoi.io)"  # 通用

基本操作：

 1# 初始化（會建立 source directory 和 Git repo）
 2chezmoi init
 3
 4# 加入現有配置
 5chezmoi add ~/.zshrc
 6chezmoi add ~/.config/nvim
 7
 8# 編輯（在 source directory 裡編輯，不是直接改家目錄的檔案）
 9chezmoi edit ~/.zshrc
10
11# 預覽差異
12chezmoi diff
13
14# 套用到家目錄
15chezmoi apply
16
17# 推上遠端
18chezmoi cd  # 進入 source directory
19git add -A && git commit -m "update" && git push

chezmoi 的核心優勢是 template。同一份配置檔在不同機器可以產生不同內容：

 1# chezmoi 的 source directory 裡，檔案名稱加 .tmpl 後綴
 2# dot_zshrc.tmpl
 3
 4export EDITOR="nvim"
 5
 6{{- if eq .chezmoi.os "darwin" }}
 7export HOMEBREW_PREFIX="/opt/homebrew"
 8eval "$($HOMEBREW_PREFIX/bin/brew shellenv)"
 9{{- end }}
10
11{{- if eq .chezmoi.os "linux" }}
12export PATH="$HOME/.local/bin:$PATH"
13{{- end }}

chezmoi apply 會根據當前機器的 OS 展開 template，macOS 上產生的 .zshrc 會包含 Homebrew 設定，Linux 上不會。

Secret 管理是另一個殺手功能。chezmoi 整合了 1Password、Bitwarden、pass、gopass、LastPass 等密碼管理器：

1# dot_gitconfig.tmpl
2[user]
3    name = Your Name
4    email = {{ (onepasswordRead "op://Personal/Git Config/email").value }}

chezmoi apply 時會即時從 1Password 拉值填入，secret 不會存在 Git repo 裡。

chezmoi 適合管理多台異質機器（macOS 工作機 + Linux 伺服器 + Linux 桌面 VM）且有 secret 需求的人。它的代價是學習曲線最陡——要理解 chezmoi 自己的目錄命名慣例（dot_ 前綴代表 . 開頭、private_ 前綴代表權限 0600）、template 語法（Go template）、以及「source directory 和目標位置是兩份獨立的檔案」這個心智模型。

選型判讀

選工具看三個維度：機器數量、OS 組合、secret 需求。

只有一台機器、配置簡單 — bare repo 或 stow 都夠用，差別在於你喜不喜歡 symlink 的管理方式。bare repo 最輕量，stow 多一層模組化。

多台同質機器（都是 macOS 或都是 Linux）— stow。配置檔在同 OS 間差異小，不需要 template，stow 的模組化讓你可以只在桌面機安裝 hyprland package、伺服器只裝 zsh + git + tmux。

多台異質機器（macOS + Linux）但 secret 需求不高 — stow 加上 OS 分流仍然可行，跨平台共用一個 Repo 會完整說明做法。

多台異質機器、需要條件安裝但不想學 template 語法 — yadm。alternate files 讓你依 OS/hostname 切換整個配置檔，內建 encrypt 處理 secret，Git 操作方式跟 bare repo 相同。

多台異質機器（macOS + Linux）、有細粒度 template 或密碼管理器整合需求 — chezmoi。檔案內的段落條件、跟 1Password/Bitwarden 的整合、private_ 前綴的 permission 管理是它存在的理由。

不確定 — 從 stow 開始。它的概念最直覺（目錄結構 = 安裝後位置）、遷移成本最低（要換到 yadm 是加一層 wrapper、要換到 chezmoi 時目錄結構的概念是相通的）。

開始之前，確認 SSH key 和 Git 已經設好、dotfile repo 已經 clone 到本機——這些前置步驟見環境建置的操作順序的階段一。

章節文章

跨分類引用

• → 模組零：Dotfile 心智模型：為什麼要管理、哪些東西該進 repo
• → 模組二：Shell 配置：目錄結構裡 zsh package 的具體拆法
• → 模組八：同步、Bootstrap 與環境重建：跨機器同步策略與 secret 管理

什麼是 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 不可讀、很多是應用程式自動產生的。

這篇給每個關鍵選項一條判斷軸，而不是一份「照著點」的步驟。底下用一次具體的安裝當作貫穿例子：在 Apple Silicon 的 UTM 上用 archboot ISO 裝 Arch Linux ARM，目標是一台演練 dotfile 部署的測試 VM。例子是具體的，但判斷軸跨發行版通用——locale、分割、bootloader 這些抉擇在多數 Linux 安裝程式裡都會以類似形式出現。

怎麼建立 VM、燒錄並開機到安裝程式，是跟環境綁定的前置——UTM、VirtualBox、實體機各不相同——不在這條判讀軸的範圍；這篇從「安裝程式已經跑起來、開始問你選項」接手，給的是每個選項的判斷軸，不逐頁帶某個安裝程式的選單怎麼點。底下的指令與選單名稱以 archboot / Arch 呈現，換 Ubuntu（Subiquity 安裝程式）或 Fedora 時，選項的判斷軸一樣成立，但選單長相、套件組名稱、指令會不同。

系統語系與時間

系統語系決定的是錯誤訊息、log、系統工具輸出用哪種語言，不是你日常打字的語言。這兩件事容易混為一談。日常輸入中文是桌面層的字型與輸入法問題，跟系統 locale 無關；系統 locale 影響的是當某個服務崩潰、你在 journalctl 裡讀它吐出來的那行訊息時，那行字是英文還是被翻譯過。

把系統 locale 留在 en_US.UTF-8 的理由是可搜尋性。當你把一段錯誤訊息貼到搜尋引擎或問別人，英文訊息能對上絕大多數的文件、issue、Stack Overflow 答案；翻譯過的訊息往往一個結果都搜不到。這條判斷軸對伺服器、開發機、任何你預期會除錯的機器都成立。會選非英文 locale 的情境通常是給終端使用者的桌面，且該使用者不除錯——那是另一種機器。

時區的選擇影響 log 的時間戳跟排程任務的觸發時刻，挑你所在地即可。另一個相關的決策是「硬體時鐘存 UTC 還是本地時間」：選 UTC。Linux 慣例是硬體時鐘存 UTC、顯示時再換算成時區，這樣跨時區搬機器、或 NTP 校時都不會錯亂。會需要存本地時間的唯一常見情境是跟 Windows 雙開——Windows 預設把硬體時鐘當本地時間——而 VM 或純 Linux 機器沒有這個包袱。

網路

安裝階段的網路設定要回答兩個層次：當下能不能連、以及這份設定會不會帶進裝好的系統。第一層通常很直覺——選到對的網卡、用 DHCP 讓它自動拿 IP。虛擬機的 NAT 網路會自動發 IP，所以選 DHCP、不要手動設 static，省去算網段的麻煩。

第二層是真正會咬人的地方：安裝程式裡設好的網路，不保證會出現在重開機後的系統裡。這是 VM 裝 Linux 常見的斷網點——安裝時明明能上網裝套件，重開機後卻連不出去，因為安裝環境的網路設定沒被複製到目標系統。判讀方式是裝好首次開機後立刻驗證：看網卡有沒有拿到 IP、能不能解析一個域名。

1ip -brief a          # 網卡有沒有 IP、狀態是不是 UP
2ping -c 3 archlinux.org   # 解析成功就證明對外連線 + DNS 都通

DNS 能把域名解析成 IP，本身就證明對外連線是通的（DNS 查詢就是一次網路往返），所以這條 ping 即使對方不回 ICMP 也已經給了答案。在前述的 archboot 例子裡，網路設定確實有被複製進目標系統並由 systemd-networkd 接手，重開機後免再手動設——但這是該安裝程式的行為，不能假設每個安裝程式都這樣。把「首次開機驗網路」當成固定動作，比預設它一定會通安全。

套件鏡像

鏡像源決定你從哪裡下載套件，挑地理上接近的那個。基礎系統加上一套桌面動輒上 GB，選對岸的鏡像跟選同城的鏡像，下載時間差好幾倍。安裝程式給的鏡像清單通常按國家排，往下捲找你所在地區的；找不到完全同國的，就退而求其次選同區域、且穩定的大型鏡像。

這個選擇的另一個作用是順帶確認你裝的是哪個發行版分支。前述例子的鏡像清單全是 archlinuxarm.org，這證實了 archboot 的 aarch64 ISO 裝出來的是 Arch Linux ARM（ARM 移植版），而不是 x86 的 Arch——同一條安裝路徑產出的是哪個分支，鏡像來源會洩漏給你看。

磁碟分割

磁碟分割是整個安裝裡選項最多、也最不可逆的一段，但判斷軸只有一條：這台機器需不需要在分區層面做隔離。需要隔離的情境——多系統共存、加密、資料與系統分離以便重灌不丟資料——每多一個，分割就多一層結構。不需要的情境，多切一刀都只是增加「一邊爆一邊空」的風險。下面逐項拆解，但它們服務的是同一個判斷。

自動分割 vs 手動分割

自動分割（清空整碟、安裝程式幫你建標準佈局）適用於整碟專屬、沒有要保留任何既有資料的機器。測試 VM 的磁碟是全新的、整碟給這個系統用，自動分割沒有任何代價，還省去手動算 EFI 大小、root 大小、對齊、格式化、掛載這一連串容易錯的步驟。

手動分割的價值在你需要非標準佈局時才浮現：多系統共用某個分區、要留一塊不格式化的資料區、要套 LVM 或 LUKS。這些是真實主力機與伺服器會遇到的需求，但對一台「目標是驗證 dotfile 部署」的 VM 是純雜訊——它們屬於另一個主題，不該混進這次的安裝。判讀訊號很簡單：你說得出一個具體的隔離需求，才手動分割；說不出來，自動分割就是對的。

分區識別方式（PARTUUID）

分區識別方式決定 fstab（開機時決定哪個分區掛到哪的設定檔）跟 bootloader 怎麼指涉每個分區，在 GPT（現代 UEFI 機器的分區表格式）磁碟上選 PARTUUID。這個選擇的後果是「重開機後系統找不找得到自己的分區」。PARTUUID 綁在分區本身、跨重開機穩定，而且重新格式化檔案系統也不會變；相對地，檔案系統層級的 UUID 一重格就變，會讓 fstab 失效，而 /dev/vda1 那種 kernel 名稱會隨偵測順序浮動，最不穩。穩定性的排序是 PARTUUID 優於 FSUUID 優於 kernel 名稱，GPT 磁碟用最穩的那個（這三種識別方式的細節見 分區識別卡）。

EFI 分區的掛載點與大小

EFI 系統分區（ESP）放開機載入器與 kernel，掛載點的選擇取決於這台機器是不是單一作業系統。把 ESP 掛在 /boot（單系統佈局）讓 kernel 跟開機檔住在同一個分區、維護最單純；把 ESP 掛在 /efi、kernel 另放（多系統佈局）是為了多個 OS 共用同一個 ESP 才需要的結構。單系統的機器選多系統佈局，只是憑空多一層目錄。

ESP 大小在單系統佈局下要算進 kernel 與 initramfs（開機初期把真正的 root 掛起來之前、用來載入驅動的小型臨時根檔系統）。一個 kernel 加上它的 initramfs（含 fallback）大約一兩百 MB，再加上 FAT32 ESP 約 260 MiB 的實務下限，512 MiB 是在下限之上留餘裕。會需要更大的情境是你要同時保留多個 kernel 版本——但單 kernel 的 VM 用不到，給太大只是浪費。

Swap

Swap 是記憶體不足時的安全墊，大小取決於這台機器的記憶體壓力型態，不是一個固定公式。對一台只有 4 GB RAM、且要在上面從原始碼編譯套件的 VM，編譯瞬間的記憶體尖峰很容易把實體記憶體吃爆、觸發 OOM 把進程殺掉。給 2 GB swap 當緩衝，擋住這種尖峰、避免安裝跑到一半被中斷。

swap 分區的磁碟成本不是一次付清的。mkswap 只寫一個 header，實際沒被換出的頁不會佔用宿主磁碟空間（在稀疏配置的虛擬磁碟上尤其明顯），用到才寫。所以「為了保險多給一點 swap」的代價，比直覺以為的小。判讀軸是看工作負載：會編譯、會跑吃記憶體的服務、RAM 又緊，就給足 swap；純文書、RAM 寬裕，小一點或不給都行。

swap 還有形態的選擇，這裡用分區 swap 是因為在安裝程式階段一併切好最省事，不代表它比另兩種好。swapfile（一個檔案，事後可隨時調大小或移除）避開了「分割最不可逆」的痛點；zram（壓縮記憶體 swap，不碰磁碟）對低 RAM 加編譯尖峰正是設計情境，現代發行版很多預設用它。換句話說，2 GB 這個量是看編譯尖峰定的，而「切成分區」只是配合安裝當下一次到位——若你跳過安裝期的 swap、事後用 swapfile 或 zram 補，是等價的可逆路徑。

檔案系統

檔案系統的選擇是在「簡單可靠」與「進階功能」之間取捨，預設往簡單那邊靠。ext4 簡單、穩、在各平台行為一致、修復工具成熟，對一台只要求「可靠地存取檔案」的機器是零驚喜的選擇。btrfs 提供快照、subvolume、透明壓縮，但代價是要規劃 subvolume 佈局、還要理解它寫時複製（CoW）的一些行為差異；這些功能在你會用快照回滾的主力機上很有價值，在演練 VM 上是雜訊。xfs 同樣穩定，但對這類用途相對 ext4 沒有決定性優勢。更特定的 zfs、f2fs 不在一般 VM 的考慮範圍——zfs 在 Arch / ARM 上是非主線 kernel 的 out-of-tree 模組、授權與維護成本高，f2fs 是為快閃裝置設計、VM 用不到。

判讀軸是你會不會用到進階功能。會固定用快照回滾系統狀態——選 btrfs 並接受它的佈局複雜度；只是要一個可靠的檔案系統——ext4。快照這類能力跟下面的獨立 /home 一樣，是真實機器的儲存規劃主題，值得另外深入，但別為了「聽起來比較強」就把它的複雜度帶進一台用完即丟的機器。

獨立 /home vs 單一 root

獨立 /home 分區的價值是「重灌系統不丟個人資料」，這是主力機的需求，不是每台機器都需要。把 /home 切成獨立分區，重裝系統時可以只格式化 root、保留 /home 裡的設定與檔案。一台用完即丟的演練 VM 沒有這個需求——它的整個生命週期就是裝起來、驗證、丟掉。如果你想跨多次實驗保留狀態，VM 情境更貼切的手段是宿主層的快照或共享資料夾，而不是在 guest 裡切獨立 /home——後者解決的是「重灌 OS 保資料」，不是「保留實驗狀態」。

把空間切兩半的隱性代價是失衡風險。假設總共十幾 GB，照預設切一塊給 /、剩下給 /home，所有系統套件（桌面全套依賴都裝在 /usr、算 /）擠在前者、容易先滿，而 /home 那邊空著——典型的一邊爆一邊空。把全部空間當一個池子用的單一 root 佈局，不會人為卡死任一邊，對不需要「重灌保資料」的機器最不容易出事。

Bootloader

開機載入器決定韌體怎麼找到並載入 kernel，在虛擬機上選 GRUB 而非直接用 EFISTUB，理由是可靠性（韌體到 kernel 的整條交棒過程見 UEFI 開機鏈卡）。EFISTUB 讓 UEFI 韌體直接載入 kernel、不經過獨立的 bootloader，最精簡，但它完全依賴寫進 UEFI NVRAM（韌體用來存開機項的非揮發記憶體）的開機項。問題在於 QEMU 系的虛擬機（UTM 底層即是）對 EFI 變數的儲存有時不穩，一旦 NVRAM 裡的開機項掉了，韌體就找不到 kernel、機器開不了——這在 VM 環境是會實際踩到的坑。

GRUB 的容錯來自它（以 removable 模式安裝時）多寫了一份。除了 NVRAM 開機項，grub-install --removable 會在 ESP 的標準 fallback 路徑（aarch64 是 \EFI\BOOT\BOOTAA64.EFI）也放一份，就算 NVRAM 開機項丟了，韌體仍會從 fallback 路徑找到 GRUB；VM 環境的安裝程式通常以這個模式裝 GRUB，正是看上這層保險。它還附帶一個開機選單，當 kernel 或 initramfs 出問題時，可以進選單救援、加開機參數除錯——演練時的容錯空間大很多。

判讀軸是環境的 NVRAM 可靠度。在 NVRAM 穩定的實體機上，EFISTUB 的極簡是漂亮的選擇；在 NVRAM 可能不穩的 VM 上，可靠性優先，GRUB 的「多寫一份 fallback + 救援選單」更穩妥。GRUB 不是唯一的可靠選擇——systemd-boot 同樣是有開機選單、能裝到 fallback 路徑的獨立 bootloader，又比 GRUB 輕，在 VM / 單系統同樣站得住；這裡落在 GRUB 是因為 archboot 安裝程式預設以 removable 模式裝它，不是 GRUB 獨佔可靠性。GRUB 自己的設定檔在 VM 上用預設值即可，不需要額外的 kernel 參數。

下一步

選項選完、系統裝好、重開機進得去之後，先別急著開始用——「裝好了」跟「能用了」之間往往還缺一截：這台最小系統不一定有你需要的基本工具。最小安裝後的工具驗證與補足 就是在補那一截。

從安裝到桌面就緒的完整依賴順序，見 模組零的操作順序指引；本篇是它「安裝作業系統」那一步的展開。

場景一：Hyprland compositor crash

症狀：所有視窗同時消失，螢幕變黑或回到 TTY 登入畫面。滑鼠鍵盤有反應（可以切 TTY），但沒有桌面。

原因：Compositor process 遇到 fatal error 被 kernel 終止。常見觸發條件包括 plugin 相容性問題、特定 Wayland 協議操作觸發的 bug、GPU driver 回傳異常狀態。

恢復步驟：

注意：以下步驟中 killall Hyprland 或重啟 Hyprland 會終止所有由 compositor 管理的視窗，未存檔的工作會遺失。如果可能，先透過 TTY 或 SSH 嘗試存檔（如 kill -USR1 <pid> 對支援的應用程式觸發存檔）。

1. Ctrl+Alt+F2 切到 TTY2
2. 用你的帳號登入
3. 檢查 Hyprland 的最後錯誤訊息：

1# 通用方式（不管 Hyprland 怎麼啟動都有效）
2journalctl -b | grep -i hypr | tail -30
3
4# 如果 Hyprland 是 systemd user unit，可以更精準地查：
5journalctl --user -u hyprland -n 50 --no-pager

4. 重新啟動 Hyprland：

1Hyprland

5. 如果反覆 crash，檢查最近改過的 config：

1cd ~/.config/hypr
2git diff  # 如果 dotfile 有版控

預防：config 改動後用 hyprctl reload 測試，不要直接重啟。啟用 plugin 前確認版本跟 Hyprland 版本相容。

場景二：單一桌面工具掛了

症狀：狀態列（waybar）消失、啟動器（wofi/rofi）叫不出來、通知（mako/dunst）不跳了。桌面其他功能正常，視窗可以操作。

原因：這些工具各自是獨立的 process。掛了只影響自己的功能，不影響 compositor 或其他工具。常見原因是 config 語法錯誤（改完 config 後觸發）、記憶體洩漏（長時間運作後）、或外部服務連線異常（如 waybar 的某個 module 連不到系統匯流排）。

恢復步驟：

判斷啟動方式：如果工具是在 Hyprland config 裡用 exec-once（Hyprland 的自動啟動指令，compositor 啟動時執行一次）啟動的，用 killall + 手動重啟；如果是 systemd user unit，用 systemctl --user。

exec-once 啟動方式（多數 Hyprland 安裝的預設做法）：

1# waybar 掛了
2killall waybar; waybar &
3
4# wofi 掛了
5killall wofi
6# wofi 只在需要時啟動，不用常駐
7
8# mako 掛了
9killall mako; mako &

systemd user unit 啟動方式：

1systemctl --user restart waybar
2systemctl --user restart mako

確認工具是否在跑：

1pgrep waybar  # 有輸出 = 在跑
2pgrep mako    # 沒輸出 = 沒在跑

預防：改 config 後重啟對應的工具確認語法正確。Waybar 的 config 是 JSON 格式，語法錯誤會導致它無法啟動——改完後先用 waybar 前台跑一次看有沒有錯誤訊息。

場景二點五：鎖屏卡死（hyprlock 異常結束）

症狀：鎖屏畫面消失但桌面沒回來，螢幕顯示 Hyprland 的失效保護訊息（「it looks like you locked your screen but the lockscreen app died」），或畫面全黑但系統有回應（SSH 能連、TTY 可能切得到也可能切不到）。

原因：鎖屏工具（Hyprlock、Swaylock）透過 Wayland 的 ext-session-lock 協議向 compositor 請求鎖定。鎖定狀態由 compositor 持有，唯一正常解鎖動作是鎖屏 client 通過認證後呼叫 unlock_and_destroy。如果鎖屏 client 在持鎖狀態下被殺（pkill、crash），compositor 沒收到認證信號，會維持鎖定並顯示失效保護畫面。這跟殺 waybar/mako 不同——那些是普通 process，殺了重啟就好；鎖屏 client 持有安全狀態，殺了反而卡住。

恢復步驟：

1. 嘗試切到另一個 TTY（Ctrl+Alt+F2）。注意：ext-session-lock 的安全語意允許 compositor 攔截 VT 切換快捷鍵，此時 TTY 切不過去，改用 SSH 從另一台機器連入
2. 允許新的鎖屏 client 接管既有的鎖：

1hyprctl --instance 0 'keyword misc:allow_session_lock_restore 1'

3. 重新拉一個鎖屏 client：

1hyprctl --instance 0 'dispatch exec hyprlock'

4. 回到鎖屏畫面，用密碼正常解鎖

判讀：loginctl show-session <id> -p LockedHint 可能顯示 LockedHint=no（logind 層認為沒鎖），但畫面仍進不去——因為擋住畫面的是 compositor 的 ext-session-lock，跟 logind 的提示是獨立的兩層。判斷畫面鎖定狀態看 compositor 層，不看 logind。

預防：測試鎖屏時備好恢復路徑（知道密碼、或預先開 SSH）。不要用殺 process 的方式結束鎖屏——要結束就走認證解鎖。自動化流程若會啟動鎖屏，把「需要人工解鎖」算進代價。鎖屏安全模型的完整說明見 Session Lock。

場景二點六：桌面 shell 畫得出來但互動死掉（進程活著卻 wedged）

症狀：bar / 狀態列還在螢幕上、看起來一切正常，但點它的按鈕（工作區切換、系統匣圖示）沒反應，keybind 叫不出啟動器（wofi / 內建 launcher）。同時焦點視窗（例如終端機）打字完全正常——鍵盤到得了應用程式，只是桌面 shell 的互動死了。

原因：這是跟場景二（工具掛了）不同的一類故障，關鍵差別在進程還活著。場景二是 process 崩潰退出（pgrep 沒輸出），殺了重啟就好；這裡的桌面 shell（如 caelestia / Quickshell）進程還在跑（pgrep 找得到、STAT 是正常的 S、在 poll 等事件、CPU 不高），但它內部的某個子系統初始化失敗了——常見是 QML scene 的某個物件因為上游錯誤沒建起來、變成 null，於是負責「keybind → 開抽屜」「bar 按鈕互動」的模組對 null 讀屬性、整條互動接線死掉。bar 之所以還畫得出來，是它還停在初始化失敗前那一幀的畫面：畫得出來不等於還活著，跟鎖屏那課（畫面有密碼框不等於真的在鎖）是同一個陷阱。

上游觸發常是渲染層。實測案例：VM 的 GPU 只提供到 GLSL 1.20，而 shell 的 shader 需要 GLES 100/300/330，pipeline 建不起來（log 狂噴 Failed to build graphics pipeline state），這次渲染失敗把 scene 初始化打斷，drawers 狀態物件變 null。

診斷（別看 pgrep，讀 shell 自己的 log）：

pgrep 在這裡會騙你——它回報「在跑」，但那不等於「在運作」。權威來源是 shell 自己的 log，而且這種 log 常常不在 journalctl、也不在你猜的路徑，要用該 shell 專屬的 log 指令：

1# caelestia 的例子：用它自己的 CLI 印 shell log
2caelestia shell -l 2>&1 | tail -40
3# 看的是 QML 的 TypeError：對 null 讀屬性 = 那個子系統死了
4#   scene: @modules/Shortcuts.qml: TypeError: Cannot read property 'launcher' of null

另一個活性探針是 shell 的 IPC 回不回真實狀態：正常時查抽屜列表會回傳名字，子系統死掉時回空——這比「進程在不在」精準得多：

1# 子系統活著 → 列出 bar/launcher/session…；死掉 → 回空
2caelestia shell ipc call drawers list

恢復步驟：重啟 shell 讓 scene 重建。以 caelestia 為例：

1caelestia shell -k     # 殺掉卡住的 shell
2caelestia shell -d     # 重新啟動（detached）

驗證修好了，看子系統回來、不是看 pgrep：重啟後 process 一定在（pgrep 本來就會有），要確認的是接線恢復——caelestia shell ipc call drawers list 從「回空」變成列出真實抽屜名、log 不再噴 null 的 TypeError。這對應「重啟成功要驗子系統狀態、不是驗 process 存在」的通用紀律。

判讀與其他場景的界線：pgrep 有輸出 + bar 畫得出來 → 別急著判「正常」；點不動 / keybind 死掉就是 wedged 的訊號，往 shell 自己的 log 查。這跟場景二（process 真的沒了、pgrep 空）、場景三（compositor 整個凍結、連終端機打字都不行）都不同——這裡 compositor 正常、焦點視窗鍵盤正常，只有 shell 的互動接線死。判「進程活著到底有沒有在運作」的通用招式，見 程序、服務與狀態怎麼判。

預防：留意 shell log 裡持續出現的 shader / 渲染 pipeline 錯誤——在 VM 或 GL 支援不足的環境，這類錯誤可能非致命地存在（shell 大致能用），但一次渲染失敗就可能打斷 scene 初始化、把互動接線弄死。VM 環境要確認 GPU 提供的 GL / GLSL 版本足夠（virtio-gpu 走 mesa/zink 提供 GL 3.3+），或在 shell 設定關掉需要高階 shader 的效果。

場景三：GPU driver hang（畫面凍結）

症狀：桌面畫面完全凍結——滑鼠不動、鍵盤不回應、Ctrl+Alt+F2 切 TTY 也沒反應或延遲很久才回應。但如果從另一台機器 SSH 進來，系統是活的，process 都在跑。

原因：GPU driver 進入異常狀態。NVIDIA 閉源驅動在 Linux 上的穩定性不如 AMD 開源驅動（amdgpu），特別是在 Wayland 環境下。常見觸發條件包括 suspend/resume 之後 GPU 沒正確恢復、某些 OpenGL/Vulkan 操作觸發 driver bug、顯示輸出切換（接上或拔掉外接螢幕）。

恢復步驟：

方法 A — 如果 TTY 能切過去：

1# 切到 TTY2
2Ctrl+Alt+F2
3
4# 殺掉 Hyprland（它會帶走所有視窗）
5killall Hyprland
6
7# 重新啟動
8Hyprland

方法 B — 如果 TTY 也凍結、但 SSH 能連：

 1# 從另一台機器 SSH 進來（需事先知道 IP，見下方預防段）
 2ssh user@machine-ip
 3
 4# 殺掉 compositor
 5killall Hyprland
 6
 7# 如果需要 reset GPU（NVIDIA，且 driver 仍回應）
 8# 前提：所有使用 GPU 的 process 已停止（compositor 已 kill）
 9sudo nvidia-smi --gpu-reset
10
11# 切回機器前面重啟 Hyprland

方法 C — 如果完全無回應，先嘗試 Magic SysRq：

Magic SysRq 是 kernel 層級的緊急操作介面，即使 userspace 完全卡死也能回應。按住 Alt+SysRq（筆電通常是 Alt+Fn+SysRq），然後依序按 R E I S U B（每個鍵間隔幾秒）：

• R — 把鍵盤從 raw mode 搶回來
• E — 對所有 process 送 SIGTERM
• I — 對所有 process 送 SIGKILL
• S — sync 所有檔案系統
• U — remount 所有檔案系統為 read-only
• B — 立即 reboot

這比直接斷電安全——sync + unmount 步驟會盡量保護磁碟上的資料。Arch Linux 預設可能停用 SysRq，需在 /etc/sysctl.d/ 設定 kernel.sysrq=1 啟用。

方法 D — 如果 SysRq 也無效，按住電源鍵強制關機：

這是最後手段。Linux 的 ext4/btrfs 檔案系統有 journal 保護，強制關機通常不會損壞檔案系統結構。但 journal 保護的是 metadata 一致性，正在寫入的使用者資料（未存檔的文件、正在下載的檔案）仍然可能遺失或損壞。重開機後正常登入 TTY、啟動 Hyprland 即可。如果開機過程有異常，用 journalctl -b -1 -p err 查看上次開機的錯誤訊息，確認是否有檔案系統修復紀錄。

預防：

• NVIDIA 用戶：關注 driver 版本的 release notes，已知有 Wayland 問題的版本避開
• 配置 suspend 後的 GPU 恢復：在 Hyprland config 或 systemd sleep hook 裡加入 GPU reset 操作
• 事先記錄機器的 IP 位址（ip addr show）或設定固定 hostname（如 mDNS 的 machine.local），桌面凍結時才有辦法從另一台機器 SSH 進來
• 考慮開啟 SSH server，出問題時可以遠端救援。開啟後應配置 key-based authentication 並停用密碼登入（PasswordAuthentication no），避免在網路上暴露密碼登入通道：

1sudo systemctl enable sshd
2sudo systemctl start sshd
3
4# 安全配置：停用密碼登入（確保已設好 SSH key 再改）
5# 編輯 /etc/ssh/sshd_config，設定 PasswordAuthentication no
6# 然後 sudo systemctl restart sshd

場景四：記憶體耗盡（OOM）

症狀：系統變得極慢，操作有明顯延遲（幾秒到幾十秒）。隨後可能某些 process 突然被殺掉——瀏覽器分頁消失、IDE 視窗關閉，嚴重時 Hyprland 本身被 OOM Killer 終止導致桌面消失。

原因：實體記憶體和 swap 都用完了。常見觸發者是瀏覽器（Chrome/Firefox 的分頁越開越多）、IDE（大型專案的 language server）、Docker container、或應用程式的記憶體洩漏。

恢復步驟：

如果還能操作：

1# 找出誰在吃記憶體
2top -o %MEM
3# 或用 htop/btop 的互動介面
4
5# 殺掉佔最多記憶體的 process
6kill <PID>

如果桌面已經被殺、在 TTY 裡：

1# 看 OOM Killer 殺了誰
2journalctl -b | grep -i "out of memory"
3journalctl -b | grep -i "oom"
4
5# 清理完後重啟桌面
6Hyprland

預防：

設定 swap（即使 RAM 夠大，swap 提供 OOM 前的緩衝時間讓你有機會手動清理 process）。RAM 16GB 以上的機器，2-4GB swap 作緩衝通常足夠：

 1# 查看是否有 swap
 2swapon --show
 3
 4# 如果沒有，建立一個 4GB 的 swap file（ext4 檔案系統）
 5sudo fallocate -l 4G /swapfile
 6sudo chmod 600 /swapfile
 7sudo mkswap /swapfile
 8sudo swapon /swapfile
 9
10# 永久生效：加入 /etc/fstab
11echo '/swapfile none swap defaults 0 0' | sudo tee -a /etc/fstab

Btrfs 檔案系統不支援 fallocate 建立 swap file。Btrfs 用戶需改用 btrfs filesystem mkswapfile 或建立專屬的 swap subvolume，具體做法參考 Arch Wiki 的 Btrfs swap 段落。

啟用 systemd-oomd（比 kernel OOM Killer 更早介入、更可控）。systemd-oomd 在 cgroup 的記憶體壓力達到閾值時就開始清理，預設配置對多數桌面場景足夠。進階調整可透過 /etc/systemd/oomd.conf 設定：

1sudo systemctl enable systemd-oomd
2sudo systemctl start systemd-oomd

場景五：Config 寫錯導致 Hyprland 啟動失敗

症狀：從 display manager（圖形登入畫面，如 SDDM、GDM）登入後立刻黑屏又回到登入畫面，或直接回到 TTY。如果從 TTY 手動執行 Hyprland，看到錯誤訊息後立即退出。

原因：Hyprland config 有語法錯誤或引用了不存在的資源。常見錯誤包括 source 指定的檔案不存在、keybind 語法寫錯、monitor 設定格式錯誤。

恢復步驟：

1. 切到 TTY（Ctrl+Alt+F2）
2. 登入後直接跑 Hyprland 看錯誤訊息：

1# 看 Hyprland 的啟動錯誤（也可用 journalctl -b | grep -i hypr）
2Hyprland
3# Hyprland 如果因 config 錯誤無法啟動，會直接印出錯誤訊息後退出

3. 根據錯誤訊息修改 config：

1# Hyprland 的主 config
2vim ~/.config/hypr/hyprland.conf
3
4# 如果用了 source 拆分，錯誤訊息會指出是哪個檔案
5vim ~/.config/hypr/keybinds.conf

4. 修完後重新啟動：

1Hyprland

常見 config 錯誤：

source 路徑錯誤——檔案不存在或路徑拼錯：

1# 確認 source 指定的檔案都存在
2grep "^source" ~/.config/hypr/hyprland.conf
3# 逐一檢查每個路徑

Monitor 設定錯誤——指定了不存在的螢幕名稱：

1# 查看系統實際的螢幕名稱
2# 在能進桌面時記下來，或用 wlr-randr
3wlr-randr

Keybind 語法錯誤——dispatcher 名稱拼錯或參數格式不對。Hyprland 的 keybind 格式是 bind = MOD, key, dispatcher, params，少一個欄位或 dispatcher 拼錯就會報錯。

預防：config 改動時用 hyprctl reload 即時測試，不要改完 config 就直接重啟 Hyprland。如果 dotfile 用 Git 管理，改壞了可以 git checkout 回退。

場景六：Suspend/resume 後桌面異常

症狀：筆電蓋上或手動 suspend 後喚醒，出現以下任一情況——螢幕黑屏但系統有反應（鍵盤背光亮）、解析度跑掉、多螢幕配置丟失（所有視窗擠到一個螢幕）、compositor 直接 crash 回到 TTY。

原因：GPU driver 在 suspend/resume 過程中需要保存和恢復 GPU 狀態。NVIDIA 閉源驅動在 Wayland 上的 suspend/resume 支援不如 AMD 開源驅動穩定，特別是多螢幕配置和高刷新率模式下容易出問題。

恢復步驟：

如果螢幕黑屏但系統有反應：

1# 切到 TTY
2Ctrl+Alt+F2
3
4# 檢查 Hyprland 是否還在跑
5pgrep Hyprland
6
7# 如果在跑但沒畫面，kill 再重啟
8killall Hyprland
9Hyprland

如果解析度或螢幕配置跑掉：

1# 在 Hyprland 內重新套用 monitor 設定
2hyprctl reload

如果 compositor 已經 crash：按場景一的步驟從 TTY 重啟。

預防：

• NVIDIA 用戶：在 /etc/modprobe.d/nvidia.conf 啟用 preserve video memory allocations：

1# /etc/modprobe.d/nvidia.conf
2options nvidia NVreg_PreserveVideoMemoryAllocations=1

同時啟用 NVIDIA 的 suspend/resume systemd service：

1sudo systemctl enable nvidia-suspend
2sudo systemctl enable nvidia-resume
3sudo systemctl enable nvidia-hibernate

• AMD 用戶：amdgpu driver 的 suspend/resume 通常開箱即用，遇到問題先更新 kernel（pacman -Syu linux）。

範例結構

 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 配置，形成完整的重建鏈路。

共用的核心原則

• 宣告式：描述「環境應該長什麼樣」，而非「操作了哪些步驟」。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 可讀、跨機器部署不會帶進不必要的狀態。

核心規則

Stow 的核心規則只有一條：package 目錄內的路徑結構，就是安裝後相對於目標目錄的路徑結構。

1~/dotfiles/zsh/.zshrc          → ~/.zshrc
2~/dotfiles/nvim/.config/nvim/  → ~/.config/nvim/
3~/dotfiles/git/.gitconfig      → ~/.gitconfig

每個頂層目錄（zsh/、nvim/、git/）是一個 stow package，可以獨立安裝或移除。

常用指令

 1cd ~/dotfiles
 2
 3# 安裝：在目標目錄（預設 $HOME 的上一層，通常用 --target）建立 symlink
 4stow zsh                # 安裝 zsh package
 5stow zsh git nvim tmux  # 批次安裝多個 package
 6stow */                 # 安裝所有 package
 7
 8# 移除：刪除該 package 建立的 symlink
 9stow -D nvim
10
11# 重新安裝（移除 + 安裝）
12stow -R zsh
13
14# 收養：如果目標位置已有檔案，--adopt 把它移進 repo 再建 symlink
15stow --adopt zsh

--adopt 是首次把現有配置納入 dotfile 管理時的關鍵操作——它把家目錄的既有檔案「收養」進 repo（移動過去），然後建 symlink。之後 git diff 就能看到 repo 版本跟原版的差異。

Folding 與 Unfolding

Stow 會自動判斷要 symlink 整個目錄還是逐一 symlink 檔案：

• Folding：目標目錄不存在、或目錄內所有檔案都由同一個 package 管理 → symlink 整個目錄
• Unfolding：目標目錄已有其他來源的檔案 → 展開成逐檔 symlink，保留既有檔案不受影響

這個機制讓多個 package 可以共存於同一個目標目錄（如 ~/.config/）。

限制

• 只管 symlink 映射，不管套件安裝（套件由 Brewfile 或 packages.txt 處理）
• 不管 file permission——需要 0600 的 secret 檔靠 symlink 繼承來源權限，無法在部署時自動 chmod
• 沒有 template 機制——同一份配置在不同機器要不同內容時，需要在配置檔內用 shell 的 OS 判斷處理

完整選型比較見管理策略與選型。

配置檔位置與格式

Hyprland v0.55 起，配置格式從 hyprlang（.conf）遷移到 Lua（.lua）。主配置檔是 ~/.config/hypr/hyprland.lua。如果 .lua 不存在但 .conf 存在，Hyprland 會回退讀取舊格式，但 hyprlang 已標記為棄用，後續版本會移除支援。

修改後即時生效（不需要重新登入或重啟）。第一次啟動時如果沒有配置檔，Hyprland 會自動產生範例配置。即使配置有語法錯誤，緊急快捷鍵（SUPER+Q 開 terminal、SUPER+M 離開）仍然可用。

[VM 可測試] 配置檔格式和載入行為在 VM 裡跟實機完全相同。

模組化拆分

用 Lua 原生的 require() 拆分配置：

1-- ~/.config/hypr/hyprland.lua — 主入口
2
3require("monitors")      -- 載入 monitors.lua
4require("keybinds")      -- 載入 keybinds.lua
5require("rules")         -- 載入 rules.lua
6require("autostart")     -- 載入 autostart.lua
7require("appearance")    -- 載入 appearance.lua
8require("env")           -- 載入 env.lua

require("monitors") 會從同目錄載入 monitors.lua。拆分的理由是職責分離——改 keybind 不用在千行配置裡找位置，每個子檔案可以獨立 diff 和 rollback。

從舊格式遷移

Hyprland 官方提供遷移工具：hyprlang2lua（Go，也有瀏覽器版）和 hypr-migrate。如果你是從零開始，直接用 Lua 格式。

Monitor 設定

Monitor 設定是硬體相關的核心配置，每台機器都不同。

 1-- ~/.config/hypr/monitors.lua
 2
 3hl.config({
 4    monitor = {
 5        -- 語法："name, resolution@refreshrate, position, scale"
 6        "DP-1, 2560x1440@144, 0x0, 1",
 7        "HDMI-A-1, 1920x1080@60, 2560x0, 1",
 8
 9        -- 筆電內建螢幕
10        "eDP-1, preferred, auto, 1.5",
11
12        -- 預設規則（未明確列出的螢幕）
13        ", preferred, auto, 1",
14
15        -- 鏡像模式（DP-2 鏡像 DP-1 的畫面）
16        -- "DP-2, preferred, auto, 1, mirror, DP-1",
17    },
18})

position 決定多螢幕的空間排列——0x0 是左上角原點，2560x0 表示在第一個螢幕的右邊。scale 處理 HiDPI 顯示（1.5 表示 150% 縮放）。

查詢可用的 monitor 名稱：hyprctl monitors

其他選項：

• transform, 1 — 旋轉（0=正常、1=90 度、2=180 度、3=270 度）
• vrr, 1 — 可變更新率（1=開啟、2=僅全螢幕）
• bitdepth, 10 — 10-bit 色彩

筆電合蓋行為

1-- 合蓋時關閉內建螢幕、開蓋時恢復
2-- bindl = 即使輸入鎖定也能觸發（合蓋時需要）
3hl.bindl("", "switch:on:Lid Switch", "exec", "hyprctl keyword monitor 'eDP-1, disable'")
4hl.bindl("", "switch:off:Lid Switch", "exec", "hyprctl keyword monitor 'eDP-1, preferred, auto, 1'")

[需實機測試] Monitor 位置排列、HiDPI 縮放、VRR、旋轉、多螢幕熱插拔、合蓋行為。VM 通常只有一個虛擬螢幕。

Dotfile 管理策略

Monitor 設定是典型的「機器專屬」配置。如果用 chezmoi，可以用 template 依機器名稱切換；如果用 stow，可以把 monitors.lua 排除在 Git 外、每台機器手動寫。

輸入裝置配置

 1-- ~/.config/hypr/hyprland.lua 或拆到獨立檔案
 2
 3hl.config({
 4    input = {
 5        kb_layout = "us",
 6        -- 多語系：kb_layout = "us,de",
 7        -- 切換：kb_options = "grp:alt_shift_toggle",
 8        -- Caps Lock 當 Escape：kb_options = "caps:escape",
 9        kb_options = "",
10
11        follow_mouse = 1,         -- 焦點跟隨滑鼠
12        sensitivity = 0,          -- -1.0 到 1.0（0 = 不修改）
13        accel_profile = "flat",   -- flat 或 adaptive
14
15        repeat_rate = 25,         -- 長按時每秒重複幾次
16        repeat_delay = 600,       -- 按住多久開始重複（毫秒）
17
18        touchpad = {
19            natural_scroll = true,
20            disable_while_typing = true,
21            ["tap-to-click"] = true,
22            drag_lock = false,
23            scroll_factor = 1.0,
24        },
25    },
26})

可用的 XKB options 查詢：/usr/share/X11/xkb/rules/evdev.lst 或 localectl list-x11-keymap-options。

[VM 可測試] 鍵盤 layout、repeat rate。
[需實機測試] 觸控板設定、手勢、滑鼠靈敏度/加速曲線、多鍵盤配置。

Keybind 設計

修飾鍵（Modifier）：SUPER 是哪顆鍵

keybind 由「修飾鍵 + 按鍵」組成，Hyprland 配置裡最常當主修飾鍵的是 SUPER。SUPER 是 X11/Wayland 對 Meta 鍵的稱呼，在不同鍵盤上是不同的實體鍵：

• PC 鍵盤：Windows 鍵（⊞，通常在 Ctrl 與 Alt 之間）。
• Mac 鍵盤：Command 鍵（⌘）。

其他常見修飾鍵：SHIFT、CTRL（Control）、ALT（Mac 上是 Option ⌥）。組合寫法用空格串，例如 "SUPER SHIFT"。選 SUPER 當主修飾鍵是慣例——它幾乎不跟應用程式本身的快捷鍵衝突（應用多用 Ctrl / Alt）。

在 Mac 上跑虛擬機時，實體 ⌘ 會對應到 guest 的 SUPER，但 macOS 會先攔截部分 ⌘ 組合——這層 VM 專屬的坑見 VM 環境設定。

Bind 類型

Hyprland 提供多種 bind 函式，處理不同互動模式：

[VM 可測試] 所有 keybind 邏輯和配置語法。

基本操作

 1-- ~/.config/hypr/keybinds.lua
 2
 3-- 基本操作
 4hl.bind("SUPER", "Return", "exec", "kitty")
 5hl.bind("SUPER", "Q", "killactive")
 6hl.bind("SUPER", "D", "exec", "wofi --show drun")
 7hl.bind("SUPER", "F", "fullscreen", "0")
 8hl.bind("SUPER SHIFT", "Space", "togglefloating")
 9
10-- 焦點移動（vim 風格）
11hl.bind("SUPER", "H", "movefocus", "l")
12hl.bind("SUPER", "J", "movefocus", "d")
13hl.bind("SUPER", "K", "movefocus", "u")
14hl.bind("SUPER", "L", "movefocus", "r")
15
16-- 視窗移動
17hl.bind("SUPER SHIFT", "H", "movewindow", "l")
18hl.bind("SUPER SHIFT", "J", "movewindow", "d")
19hl.bind("SUPER SHIFT", "K", "movewindow", "u")
20hl.bind("SUPER SHIFT", "L", "movewindow", "r")
21
22-- 視窗大小調整（長按連續觸發）
23hl.binde("SUPER CTRL", "H", "resizeactive", "-20 0")
24hl.binde("SUPER CTRL", "J", "resizeactive", "0 20")
25hl.binde("SUPER CTRL", "K", "resizeactive", "0 -20")
26hl.binde("SUPER CTRL", "L", "resizeactive", "20 0")
27
28-- 滑鼠綁定：SUPER + 左鍵拖曳移動、右鍵拖曳調整大小
29hl.bindm("SUPER", "mouse:272", "movewindow")
30hl.bindm("SUPER", "mouse:273", "resizewindow")
31
32-- Workspace 切換
33hl.bind("SUPER", "1", "workspace", "1")
34hl.bind("SUPER", "2", "workspace", "2")
35hl.bind("SUPER", "3", "workspace", "3")
36hl.bind("SUPER", "4", "workspace", "4")
37hl.bind("SUPER", "5", "workspace", "5")
38hl.bind("SUPER", "6", "workspace", "6")
39hl.bind("SUPER", "7", "workspace", "7")
40hl.bind("SUPER", "8", "workspace", "8")
41hl.bind("SUPER", "9", "workspace", "9")
42
43-- 把視窗送到指定 workspace
44hl.bind("SUPER SHIFT", "1", "movetoworkspace", "1")
45hl.bind("SUPER SHIFT", "2", "movetoworkspace", "2")
46hl.bind("SUPER SHIFT", "3", "movetoworkspace", "3")
47-- 以此類推
48
49-- 螢幕截圖
50hl.bind("", "Print", "exec", "grimblast copy area")
51hl.bind("SUPER", "Print", "exec", "grimblast copy output")
52
53-- 多螢幕焦點切換
54hl.bind("SUPER", "comma", "focusmonitor", "l")
55hl.bind("SUPER", "period", "focusmonitor", "r")
56hl.bind("SUPER SHIFT", "comma", "movewindow", "mon:l")
57hl.bind("SUPER SHIFT", "period", "movewindow", "mon:r")

設計原則

• SUPER（Windows/Command 鍵）當 modifier，避免跟應用程式快捷鍵衝突
• 方向操作統一用 vim 的 HJKL，降低記憶負擔
• modifier 分層：SUPER 是焦點、SUPER+SHIFT 是移動、SUPER+CTRL 是調整大小
• 常用操作（開 terminal、關視窗、切 workspace）放在最順手的位置

Submap：模態快捷鍵

Submap 類似 vim 的模式切換——進入某個 submap 後，快捷鍵的意義改變，直到離開。適合需要連續操作的場景（如調整大小）：

 1-- 按 SUPER+R 進入 resize 模式
 2hl.bind("SUPER", "R", "submap", "resize")
 3
 4-- 定義 resize 模式的快捷鍵
 5hl.submap("resize")
 6hl.binde("", "H", "resizeactive", "-20 0")
 7hl.binde("", "L", "resizeactive", "20 0")
 8hl.binde("", "K", "resizeactive", "0 -20")
 9hl.binde("", "J", "resizeactive", "0 20")
10hl.bind("", "escape", "submap", "reset")   -- Escape 離開
11hl.submap("reset")

進入 resize 模式後，直接按 HJKL（不需要 modifier）就能持續調整大小，按 Escape 回到正常模式。

媒體鍵與硬體鍵

 1-- 音量（鎖屏時也能用、長按連續觸發）
 2hl.bindel("", "XF86AudioRaiseVolume", "exec", "wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+")
 3hl.bindel("", "XF86AudioLowerVolume", "exec", "wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-")
 4hl.bindl("", "XF86AudioMute", "exec", "wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle")
 5hl.bindl("", "XF86AudioMicMute", "exec", "wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle")
 6
 7-- 亮度
 8hl.bindel("", "XF86MonBrightnessUp", "exec", "brightnessctl s 10%+")
 9hl.bindel("", "XF86MonBrightnessDown", "exec", "brightnessctl s 10%-")
10
11-- 媒體播放
12hl.bindl("", "XF86AudioPlay", "exec", "playerctl play-pause")
13hl.bindl("", "XF86AudioNext", "exec", "playerctl next")
14hl.bindl("", "XF86AudioPrev", "exec", "playerctl previous")

[需實機測試] 媒體鍵（XF86Audio*）、亮度鍵（XF86MonBrightness*）、合蓋開關——這些依賴實體硬體送出正確的 keycode。VM 鍵盤通常沒有這些鍵。

環境變數

環境變數在 hl.config() 的 env 區段設定，影響 Hyprland 自身和其下執行的應用程式：

 1-- ~/.config/hypr/env.lua
 2
 3hl.config({
 4    env = {
 5        -- 游標主題
 6        "XCURSOR_SIZE, 24",
 7        "XCURSOR_THEME, Bibata-Modern-Classic",
 8        "HYPRCURSOR_SIZE, 24",
 9        "HYPRCURSOR_THEME, Bibata-Modern-Classic",
10
11        -- Qt 應用程式
12        "QT_AUTO_SCREEN_SCALE_FACTOR, 1",
13        "QT_QPA_PLATFORM, wayland;xcb",
14        "QT_QPA_PLATFORMTHEME, qt5ct",
15        "QT_WAYLAND_DISABLE_WINDOWDECORATION, 1",
16
17        -- GTK 應用程式
18        "GDK_BACKEND, wayland,x11,*",
19
20        -- XDG session
21        "XDG_CURRENT_DESKTOP, Hyprland",
22        "XDG_SESSION_TYPE, wayland",
23        "XDG_SESSION_DESKTOP, Hyprland",
24
25        -- Electron 應用程式（VS Code, Discord 等）
26        "ELECTRON_OZONE_PLATFORM_HINT, auto",
27
28        -- Firefox
29        "MOZ_ENABLE_WAYLAND, 1",
30    },
31})

NVIDIA 專用環境變數

如果使用 NVIDIA 顯卡，需要額外設定（AMD 和 Intel 不需要）：

 1-- 只在 NVIDIA 機器上加這些
 2hl.config({
 3    env = {
 4        "LIBVA_DRIVER_NAME, nvidia",
 5        "GBM_BACKEND, nvidia-drm",             -- Firefox 若崩潰就移除這行
 6        "__GLX_VENDOR_LIBRARY_NAME, nvidia",
 7        "NVD_BACKEND, direct",
 8    },
 9    cursor = {
10        no_hardware_cursors = true,             -- NVIDIA 常見的游標問題修正
11        allow_dumb_copy = true,
12    },
13})

[VM 不適用] NVIDIA 環境變數和驅動設定在 VM 裡無意義——VM 使用 virtio-gpu 或軟體渲染。這些設定只在實體 NVIDIA 機器上測試。

VM 專用環境變數

在 VM（UTM/QEMU）裡跑 Hyprland 需要額外的回退設定：

1-- 只在 VM 裡加，實機要移除
2hl.config({
3    env = {
4        "WLR_RENDERER_ALLOW_SOFTWARE, 1",
5        "LIBGL_ALWAYS_SOFTWARE, 1",
6        "WLR_NO_HARDWARE_CURSORS, 1",
7    },
8})

[已驗證] Hyprland 0.55（Aquamarine 渲染後端）+ UTM virtio-gpu-gl-pci 實測：使用 GPU 加速時不需要 WLR_RENDERER 或 LIBGL_ALWAYS_SOFTWARE，Hyprland 自動走 VirGL/Venus 硬體路徑。WLR_NO_HARDWARE_CURSORS 仍需要（virtio-gpu 不支援硬體 cursor）。完整 VM 設定見 VM 環境設定與測試矩陣。

macOS 原生 Window Tiling（macOS 15+）

macOS Sequoia（15，2024 年 9 月）內建了 window tiling 功能：鍵盤快捷鍵把視窗貼到螢幕的半邊或四分之一、拖拉到邊緣自動貼齊（edge snap）、相鄰視窗可以組成 tile group 一起調整比例。

原生 tiling 的邊界：沒有多工作區管理、快捷鍵自訂空間有限（只能用系統偏好設定裡的固定選項）、不支援自動平鋪（仍然是手動觸發的 snap，不會在開新視窗時自動重排）。

如果「貼到半邊 + 邊緣吸附」就足夠，原生功能免安裝即可使用。以下第三方工具解決的是原生功能做不到的事：更多排列選項（Rectangle）、自動平鋪（Amethyst）、完整的鍵盤工作流加多工作區（AeroSpace / yabai）。

Rectangle

免費、開源。用快捷鍵把視窗貼到螢幕的半邊、三分之一、角落。不是自動平鋪——每個視窗都要你主動下指令。安裝後開箱即用，學習成本最低。

適合的情境：只需要快速排版、不想花時間學新操作邏輯、偶爾分割就滿足需求。

配置檔位置：~/Library/Preferences/com.knollsoft.Rectangle.plist（macOS plist 格式，不太適合手動編輯，通常用 GUI 設定）。

Amethyst

自動平鋪，安裝後視窗就會自動排列。提供多種 layout（tall, wide, fullscreen, column 等）可以用快捷鍵切換。設定比 Rectangle 多但比 yabai 少，是「想要自動平鋪但不想深度折騰」的選擇。

配置檔：~/.amethyst.yml，YAML 格式，可以版控。

AeroSpace

近年最受歡迎的選擇。核心優勢是不需要關閉 SIP（System Integrity Protection）——它用自己實作的虛擬工作區概念，不依賴 macOS 原生的 Spaces，因此繞過了很多系統層的限制。

配置是純文字的 TOML 檔 ~/.aerospace.toml，改完即時生效。工作區模型靈活，多螢幕支援被普遍認為比 yabai 穩定。

 1# ~/.aerospace.toml 片段
 2after-startup-command = ['workspace 1']
 3
 4[gaps]
 5inner.horizontal = 10
 6inner.vertical = 10
 7outer.left = 10
 8outer.right = 10
 9
10[mode.main.binding]
11alt-h = 'focus left'
12alt-j = 'focus down'
13alt-k = 'focus up'
14alt-l = 'focus right'
15alt-shift-h = 'move left'
16alt-shift-j = 'move down'
17alt-shift-k = 'move up'
18alt-shift-l = 'move right'
19alt-1 = 'workspace 1'
20alt-2 = 'workspace 2'
21alt-3 = 'workspace 3'

配置結構直覺：gaps 控制視窗間距、binding 定義快捷鍵對應的動作。整份檔案進 dotfile repo 就能跨機器還原操作習慣。

yabai + skhd

功能最完整的 macOS tiling WM。yabai 負責視窗管理，skhd 負責快捷鍵綁定。支援 BSP（binary space partitioning）樹狀分割——每次開新視窗都是把現有空間二分，形成一棵樹，你可以操作樹的節點來旋轉、交換、調整比例。

代價是部分進階功能（某些視窗操作、取消動畫）需要部分關閉 SIP。對某些人這是門檻，對另一些人不是問題。

配置檔是 shell script：.yabairc（yabai 設定）和 .skhdrc（快捷鍵設定），進 dotfile repo 管理。

 1# .yabairc 片段
 2yabai -m config layout bsp
 3yabai -m config window_gap 10
 4yabai -m config top_padding 10
 5yabai -m config bottom_padding 10
 6
 7# 某些 app 不適合平鋪，設為浮動
 8yabai -m rule --add app="System Preferences" manage=off
 9yabai -m rule --add app="Calculator" manage=off
10yabai -m rule --add app="Finder" title="Info" manage=off

選型判讀

選工具的判準不是「哪個最強」，而是「你願意花多少時間、想要多少控制權」。

只需要快速排視窗、不想改工作習慣，Rectangle 足夠。想要自動平鋪但學習曲線要短，Amethyst 是進入點。想要完整的平鋪工作流、多工作區管理、純文字配置、又不想動系統安全設定，AeroSpace 是目前多數人推薦的首選。想要最大的控制權、願意處理 SIP 和更複雜的配置，yabai 給你最多彈性。

從 Rectangle 跳到 AeroSpace 或 yabai 是一次操作思維的轉換——從「我指定每個視窗去哪」變成「我操作版面結構、WM 負責排列」。這個轉換需要一兩週的適應期，適應期內效率會暫時下降。

tmux

tmux 是最成熟、生態最廣的選擇。配置在 ~/.config/tmux/tmux.conf（新版）或 ~/.tmux.conf（傳統位置）。

核心配置項目

 1# prefix key（預設是 Ctrl-b，很多人改成 Ctrl-a）
 2unbind C-b
 3set -g prefix C-a
 4bind C-a send-prefix
 5
 6# 分割 pane 的快捷鍵（預設不直覺，改成 | 和 -）
 7bind | split-window -h -c "#{pane_current_path}"
 8bind - split-window -v -c "#{pane_current_path}"
 9
10# 用 vim 風格的 hjkl 切換 pane
11bind h select-pane -L
12bind j select-pane -D
13bind k select-pane -U
14bind l select-pane -R
15
16# 啟用滑鼠支援
17set -g mouse on
18
19# 256 色支援
20set -g default-terminal "tmux-256color"
21set -ag terminal-overrides ",xterm-256color:RGB"
22
23# status bar 位置
24set -g status-position top

tmux plugin

用 TPM（Tmux Plugin Manager）管理，常用：

• tmux-sensible：合理的預設值
• tmux-resurrect：重開機後還原 session 佈局
• tmux-continuum：自動儲存 session

zellij

zellij 是較新的替代品，Rust 寫的，內建佈局系統、tab 命名、浮動 pane。配置在 ~/.config/zellij/config.kdl（KDL 格式）。

跟 tmux 的主要差異：

• 開箱即用的 UI 提示（底部顯示可用快捷鍵），學習曲線較低
• 佈局用 KDL 宣告式描述，比 tmux 的 script 式設定更容易管理
• Plugin 系統用 WASM，跟 tmux 的 bash script 式 plugin 不同
• 生態較新、plugin 和整合沒有 tmux 多

選型判讀

已經熟 tmux 的人通常沒有強烈理由遷移；從零開始的人 zellij 的上手成本更低。

深入

這篇是多工器的概覽（在終端機生態裡的定位、tmux 與 zellij 的取捨）。把它們當「遠端工作工具」深入用——session 持久化的核心概念、遠端斷線接回、瀏覽器連遠端 session——見工具選單的深度頁：

• tmux 持久化與基礎——session 持久化怎麼保住遠端工作。
• zellij 分頁與 pane——內建佈局的操作深入。
• zellij 遠端 web 客戶端——從瀏覽器連遠端 session。
• 遠端連線與同步工具選型——多工器之外的連線（mosh/autossh）與同步（rsync/sshfs/mutagen）。

PATH 管理

PATH 是最容易腐化的環境變數——每裝一個工具就加一條，最後 PATH 變成一長串看不懂的路徑，順序還會互相影響。

管理原則：

• PATH 設定集中在一個地方（.zshenv 或 env.zsh），不散落在多個檔案
• 新增前先想：這個路徑是所有機器都需要、還是特定機器才需要？共用的進 env.zsh，特定的進 local.zsh
• 用 typeset -U PATH (Zsh) 自動去除重複項目，避免多次 source 導致 PATH 不斷加長

1# ~/.config/zsh/env.zsh
2typeset -U PATH  # 去重
3
4# 自己的 script
5export PATH="$HOME/.local/bin:$PATH"
6export PATH="$HOME/bin:$PATH"

Plugin Manager 選型

Zsh plugin manager 的選擇很多，差異主要在載入速度和功能豐富度：

• 無 plugin manager：直接 git clone plugin 到某個目錄，手動 source。最簡單、最透明、但更新要自己管
• zinit（原 zplugin）：載入速度最快（turbo mode 延遲載入）、功能最多、但配置語法學習曲線高
• antidote：宣告式（一個 .zsh_plugins.txt 列出所有 plugin），概念簡單
• sheldon：Rust 寫的、速度快、設定用 TOML

常用 plugin：

• zsh-autosuggestions：根據歷史指令自動補全建議（灰色字，按右箭頭接受）
• zsh-syntax-highlighting：指令行即時語法高亮
• zsh-completions：額外的 tab 補全定義

Prompt 設計

Prompt 是每次按 Enter 都會看到的東西，值得花時間設計但不需要複雜。

基本款（不用框架）：

1# 顯示目錄 + git branch
2autoload -Uz vcs_info
3precmd() { vcs_info }
4zstyle ':vcs_info:git:*' formats ' (%b)'
5PROMPT='%F{blue}%~%f%F{green}${vcs_info_msg_0_}%f %# '

框架款：Starship（跨 shell、用 TOML 設定、Rust 寫的速度快）是目前最常被推薦的 prompt 工具。它的配置進 ~/.config/starship.toml，也是 dotfile 的一部分。

Dotfile 結構對應

管理工具與目錄結構裡的 stow 目錄結構，shell 配置的對應：

 1~/dotfiles/
 2└── zsh/
 3    ├── .zshenv
 4    ├── .zshrc
 5    └── .config/
 6        └── zsh/
 7            ├── aliases.zsh
 8            ├── functions.zsh
 9            ├── plugins.zsh
10            ├── prompt.zsh
11            ├── tools.zsh
12            └── env.zsh

stow zsh 會在家目錄建立 .zshenv 和 .zshrc 的 symlink，在 .config/zsh/ 下建立各模組檔案的 symlink。local.zsh 不在 repo 裡，各機器自己建。

Hyprlock 是 Hyprland 配套的鎖屏工具，支援模糊背景、自定義佈局：

 1# ~/.config/hypr/hyprlock.conf
 2
 3background {
 4    monitor =
 5    path = screenshot
 6    blur_passes = 3
 7    blur_size = 8
 8}
 9
10input-field {
11    monitor =
12    size = 250, 50
13    outline_thickness = 2
14    outer_color = rgba(137, 180, 250, 1)
15    inner_color = rgba(30, 30, 46, 1)
16    font_color = rgba(205, 214, 244, 1)
17    placeholder_text = <i>Password...</i>
18    fade_on_empty = true
19    position = 0, -50
20    halign = center
21    valign = center
22}
23
24label {
25    monitor =
26    text = $TIME
27    font_size = 64
28    font_family = MesloLGS Nerd Font
29    color = rgba(205, 214, 244, 1)
30    position = 0, 80
31    halign = center
32    valign = center
33}

鎖屏一旦啟動，桌面的「鎖定」狀態由 compositor 透過 Wayland 的 ext-session-lock 協議持有，殺掉鎖屏 process 不等於解鎖。鎖屏的安全模型與測試時的注意事項見 Session Lock。

配色系統的統一管理

Rice 的視覺品質取決於配色一致性。散亂的色碼（waybar 用一套、wofi 用另一套、mako 又一套）是桌面看起來「雜」的最常見原因。

管理方式：

選定一套配色方案。Catppuccin、Tokyo Night、Gruvbox、Nord 是目前最多 Linux ricer 使用的方案，每一套都有完整的色彩定義和各工具的預設配置。