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 這些進階功能。

核心規則

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 判斷處理

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

詞源

最被廣泛接受的說法是源自汽車改裝文化的 “rice burner” / “ricer”——原本指對（通常是日系的）平價車裝上浮誇外觀套件（大尾翼、炫光、貼紙），看起來拉風但實際性能沒提升。後來 Linux 社群借用這個概念：把桌面打扮得花俏好看，本質也是「外觀的炫技」。

也有人提出 “Race Inspired Cosmetic Enhancements” 的逆向縮寫，但普遍被認為是事後湊的解釋。

在 Linux 圈裡，rice 的原始貶意和種族色彩已經淡化，變成中性甚至帶自豪的自稱——r/unixporn 社群就是圍繞 ricing 成果的分享運轉的。

Rice 涵蓋的範圍

• 配色方案：Catppuccin、Tokyo Night、Gruvbox、Nord 等跨工具統一的色彩定義
• 狀態列：Waybar、Eww 的模組設計和 CSS 外觀
• 啟動器：Wofi、Rofi 的搜尋框外觀
• 通知：Mako、Dunst 的通知氣泡樣式
• 鎖屏：Hyprlock 的登入畫面設計
• 桌布：靜態桌布或動態桌布（Swww）
• 終端機配色：Alacritty / Kitty / Foot 的 ANSI 色碼
• 字型：Nerd Font 的 icon glyph

Caelestia 這類「desktop shell」專案把上述元件統一設計出貨，是「打包好的 rice」。手動逐一挑選和調教各元件是「DIY rice」。兩者的目標相同——視覺上協調、好看、符合個人美學。

完整的 rice 配置實務見桌面 Rice 設計。

跟 X11 的分工對照能看清它的定位。X11 時代，X server 負責畫面、一個獨立的 window manager 負責視窗排列，兩者透過協定溝通；Wayland 取消這個分家，compositor 直接兼任兩者。所以在 Wayland 語境裡，「compositor」和「window manager」常指同一個東西——Hyprland 既是 compositor 也是 tiling window manager。

它跟桌面環境（desktop environment）是不同層次。桌面環境（GNOME、KDE）是一整套元件（面板、設定、通知、檔案管理），其中內含一個 compositor；而 Hyprland 這類「只有 compositor」的方案不含那圈桌面服務，面板、啟動器、鎖屏都要另外自己接。這條「整合度 vs 自己組裝」的軸線，是桌面環境選型的主題。

compositor 在故障排除中是一個關鍵的責任邊界，因為多個系統狀態由它持有、而非別的層：

• 它握著 DRM master：直接畫到顯示裝置的獨佔權由 compositor 持有，這是為什麼 compositor 必須從實體圖形 VT 起、不能從 SSH pty 起（SSH 連線裡沒有那個 seat 與 DRM 資源），也是為什麼它跟同樣要畫到 DRM 的 kmscon 之類 userspace console 會相衝。
• 它持有 session lock 狀態：Wayland 的 ext-session-lock 鎖是 compositor 層的狀態、跟 logind 獨立，殺掉鎖屏程式 compositor 仍保持鎖定——詳見 Session Lock。
• 它掛了、桌面才真的黑：反過來說，只要 kernel 還活著、compositor 以外的東西壞了，TTY 仍能登入操作。判斷「畫面黑」是 compositor 掛了、還是沒 getty、還是顯示輸出沒接，是桌面故障排除的第一個分岔。

相關概念：TTY（不依賴 compositor 的救生通道）、Session Lock（compositor 持有的鎖定狀態）、Rice（在 compositor 上做視覺客製）。

名稱來自早期電腦透過電報打字機（teletypewriter）做輸入輸出的歷史。現代 Linux 的 TTY 是 virtual console——核心在記憶體中模擬的文字終端機，不需要實體硬體。

systemd 預設配置下有 6 個 virtual console（TTY1-TTY6）。Wayland compositor（如 Hyprland）通常佔用 TTY1 顯示圖形桌面，TTY2-TTY6 保持為純文字介面可用。

切換方式：Ctrl+Alt+F2（切到 TTY2）到 Ctrl+Alt+F6（切到 TTY6）。Ctrl+Alt+F1 切回圖形桌面（TTY1）。

TTY 在桌面故障排除中的價值在於它不依賴 compositor（Wayland 下負責畫面與視窗的核心程式）。Compositor 掛了、GPU driver 出問題導致畫面凍結——只要 kernel 還活著，TTY 就能登入操作。這是 Linux 桌面環境「掛了不等於崩潰」的關鍵機制，詳見桌面環境維護與故障排除。

相關概念：Rice（桌面客製化）、GNU Stow（dotfile 管理）。

它的責任是「把掛載真 root 所需的東西先備齊」。kernel 本身不內建所有硬體與檔案系統的驅動，當 root 位在一個需要額外驅動才讀得到的裝置上——LVM 邏輯卷、LUKS 加密卷、特殊磁碟控制器——kernel 沒辦法直接掛它。initramfs 提供一個臨時環境，把這些驅動與工具載進來、把真 root 掛起來，然後把控制權交給真 root 上的 init。

因為它要跟 kernel 一起被 bootloader 載入，所以它跟 kernel 放在同一個地方——UEFI 開機鏈裡的 ESP，或獨立的 /boot。這也是為什麼估 ESP 大小時要把它算進去：一個 kernel 加上它的 initramfs（含 fallback 版本）大約一兩百 MB。

生成工具依發行版而異：Arch 用 mkinitcpio、Fedora 用 dracut。換了 kernel 或改了開機需要的驅動，要重新生成 initramfs，否則新 kernel 可能掛不起 root。

相關概念：UEFI 開機鏈、分區識別。安裝時 ESP 大小怎麼估，見 Linux 安裝選項判讀。

UEFI 韌體開機時，要找到一個 EFI 執行檔來載入。它從兩個來源找：NVRAM（韌體用來存開機項的非揮發記憶體）裡登記的開機項，或 ESP（EFI System Partition，一個 FAT32 格式的分區）裡的標準路徑。找到的 EFI 執行檔可能是一個獨立的 bootloader，也可能直接是 kernel。

這對應兩種風格。EFISTUB 讓韌體直接載入 kernel、不經過獨立 bootloader，最精簡，但典型上依賴 NVRAM 裡的開機項。獨立 bootloader（GRUB、systemd-boot）則多一層：它有開機選單、能救援、還能裝到 ESP 的 fallback 路徑（\EFI\BOOT\BOOT<ARCH>.EFI，aarch64 是 BOOTAA64.EFI、x86_64 是 BOOTX64.EFI）。

fallback 路徑是這條鏈的保命機制。NVRAM 的開機項可能丟失——QEMU 系的虛擬機尤其容易——這時靠 NVRAM 開機項的 EFISTUB 會開不了機，而 fallback 路徑上有 bootloader 的機器，韌體仍找得到。這就是「VM 上偏好獨立 bootloader」的根據。

這條鏈預設 Secure Boot 關閉。Secure Boot 開啟時，韌體會拒載沒簽章的 EFI 執行檔（kernel 或 bootloader），這也是「重開後找不到 kernel」的一類成因——最小 VM 安裝通常把它關掉，但實體機若開著就要處理簽章。

相關概念：initramfs（bootloader 載入的對象之一）、分區識別。bootloader 選型的判讀，見 Linux 安裝選項判讀。

有三種識別方式，穩定性不同。PARTUUID 是寫在 GPT 分區表裡的 ID，綁在分區本身、跨重開機穩定，而且重新格式化檔案系統也不會變。FSUUID 是檔案系統 superblock（檔案系統開頭記錄自身中繼資料的區塊）裡的 UUID，綁在檔案系統上，所以一重新格式化就變，會讓引用它的 fstab 失效。kernel 名稱（/dev/sda1、/dev/vda1）則隨偵測順序浮動，多接一顆磁碟就可能對調，最不穩。fstab 還吃 LABEL= / PARTLABEL=（你自己給的標籤），穩定性看你維不維護那個標籤，跟前三種「系統生成」的識別不同層級，這裡不展開。

穩定性排序是 PARTUUID 優於 FSUUID 優於 kernel 名稱。在 GPT 磁碟上用 PARTUUID，得到「綁分區、重格不變」的最穩識別。這也是為什麼安裝程式問「device name scheme」時，GPT 磁碟選 PARTUUID。

理解這個差異，能解釋一類典型故障：重新格式化某個分區後機器開不了機，往往是因為 fstab 或 bootloader 用了 FSUUID，而格式化讓那個 UUID 變了。

相關概念：UEFI 開機鏈、initramfs。安裝時的識別方式選擇，見 Linux 安裝選項判讀。

這個機制發生在 fontconfig + process 記憶體層，跟顯示協議無關——Wayland 和 X11 下的行為相同。

同一時刻、兩種查詢結果

裝完新字型後，在終端機用 fontconfig 的查詢工具 fc-match（每次執行都是新 process）去查：

1fc-match ":lang=zh-tw"
2# Noto Sans CJK → 系統快取已有這支字

查得到。但同時間，一直開著的狀態列或通知 daemon 仍顯示豆腐。矛盾的根源是兩者的啟動時間不同：fc-match 剛啟動、讀到的是最新系統快取；那個豆腐的 daemon 是在裝字型之前啟動的，記憶體裡的字型清單沒有這支字。

套件管理器安裝字型時，post-install hook 通常已更新 fontconfig 的系統快取（pacman 會印 Updating fontconfig cache）。手動把字型檔放進 ~/.local/share/fonts/ 的情況下，需要自己跑 fontconfig 的快取重建工具 fc-cache：

1fc-cache -fv
2# -f 忽略時間戳、強制全部重建
3# -v 印出處理了哪些目錄

fc-cache 只更新系統快取層——磁碟上的索引檔。它不會觸及任何已啟動 process 的記憶體，跑再多次也改變不了舊 process 的字型清單。

判讀與操作

判讀訊號：fc-match 在命令列回得出正確字型，但某個一直開著的程式仍顯示豆腐，幾乎可確定是「那個程式啟動早於裝字型」。

修法是重啟該程式，不是 reload。reload 類指令（如 makoctl reload、送 SIGHUP）重讀的是設定檔——能換到 daemon 啟動時已可見的字型（例如從 A 字族改成 B 字族），但看不到啟動後才新裝的字型檔。根源是 reload 不重建記憶體裡的字型清單，只有重啟 process 才會從系統快取重新載入。

重啟的範圍取決於受影響的程式數量。單一 daemon（通知、狀態列）重啟那一個即可；由 compositor exec-once 拉起的一批元件要同時吃到新字型，最乾淨的做法是重新登入，讓它們全部重新啟動。

正常開機不會踩到這個坑——字型在開機早期就裝好，exec-once 啟動的元件從一開始就看得到完整字型集合。這個時序問題集中在「系統已經在跑、中途才補裝字型」的除錯情境。

延伸閱讀：Nerd Font 不含 CJK、需另裝 fallback 字型的具體案例見桌面 Shell 元件：狀態列、啟動器與通知；字型安裝方式見終端機與編輯器配置的字型管理段。

邊界與例外

fc-match 也查不到：連新 process 都找不到剛裝的字型，問題在系統快取層（fontconfig 索引未更新），跑 fc-cache -fv 解決。兩層的修法不同，fc-match 是分辨在哪一層的第一步。

部分應用程式支援熱載入：瀏覽器等有獨立字型服務的程式可能在開新分頁時重新掃描字型，不需要重啟整個 process。長駐 daemon（mako、waybar）與狀態列預設是啟動時載入一次。

Flatpak / Snap 的字型隔離是不同問題：沙箱化應用程式看不到 host 的字型目錄，重啟 process 也無法解決——原因不是時序，而是沙箱的檔案系統隔離。需要透過 Flatpak 的 filesystem override 或把字型放進沙箱可存取的路徑。

Wayland 下的 compositor（如 Hyprland、Sway）同時管理視窗排列與畫面輸出。鎖屏工具（Hyprlock、Swaylock）一旦啟動，桌面的「鎖定」狀態就由 compositor 透過 ext-session-lock-v1（Wayland 生態系的跨 compositor 鎖屏協議）持有。解鎖的正常動作是鎖屏 client 通過認證後呼叫 unlock_and_destroy（協議定義的 request），compositor 收到這個信號才釋放鎖定。

這個責任邊界在自動化測試、VM 演練、遠端操作時最容易出事，因為這些情境常用「殺 process」當「關掉一個東西」的通用手段。殺掉鎖屏 client 跳過了認證，compositor 不會釋放鎖——畫面會卡在失效保護狀態而非回到桌面。

logind 提示與 compositor 鎖的值可以不一致

鎖屏狀態牽涉兩個獨立的層，觸發方向和持有者不同：

loginctl lock-session 走 logind 層觸發鎖屏，鎖屏 client 收到信號後啟動、再向 compositor 取得 session lock。觸發方向是 logind → client → compositor；持有與強制執行方向是 compositor → 畫面。兩者方向相反，正好印證兩層是獨立的。

實測會遇到 LockedHint=no（logind 層說沒鎖）但畫面仍進不去——因為擋住畫面的是 compositor 的 ext-session-lock，跟 logind 提示是兩回事。判斷畫面進不進得去，看 compositor 層，不看 logind 層。

鎖屏 client 非正常結束時的失效保護

鎖屏 client 在持有鎖的狀態下死掉（被 kill、crash），compositor 沒有收到認證通過的信號，只能維持鎖定並顯示失效保護畫面。Hyprland 的失效保護畫面會直接給恢復指令：

1hyprctl --instance 0 'keyword misc:allow_session_lock_restore 1'
2hyprctl --instance 0 'dispatch exec hyprlock'

allow_session_lock_restore 允許新的鎖屏 client 接管既有的鎖（否則新 client 會因「已經鎖了」被拒）。接管後是乾淨的鎖屏 prompt，用密碼正常解鎖。

備好 restore 路徑時，殺掉無回應的鎖屏 client 是合理操作——問題不在「殺」、在「以為殺完就回桌面」。restore 的前提是有另一個可操作的 session：另一個 TTY 或 SSH 連線。ext-session-lock 的安全語意允許 compositor 攔截 VT 切換快捷鍵（Ctrl+Alt+Fn），遇到 TTY 切不過去的情況，SSH 是替代救援通道（事先配好 SSH server，見常見故障場景與恢復操作的 GPU hang 段）。

判讀與操作

• 判讀鎖定狀態：loginctl show-session $(loginctl show-user $USER -p Display --value) -p LockedHint 查 logind 層；compositor 層看畫面能否操作。兩層不一致時以 compositor 層為準。
• 正常解鎖：通過鎖屏 client 的認證（密碼 / 指紋），client 呼叫 unlock_and_destroy，compositor 釋放鎖。
• 失效保護恢復：從另一個 TTY 或 SSH 執行 hyprctl --instance 0 'keyword misc:allow_session_lock_restore 1' + hyprctl --instance 0 'dispatch exec hyprlock'，重新拉起鎖屏 prompt 後認證解鎖。
• 自動化流程的代價：啟動鎖屏後，畫面會留在鎖定狀態直到有人通過認證。自動化測試若會觸發鎖屏，要把「需人工解鎖」算進代價。
• 診斷路由：「畫面卡住 / 螢幕鎖了沒」當成一般 Linux 狀態判讀問題（跟判程式活著、判服務歸屬同類）時，見程序、服務與狀態怎麼判——它把「判 session 有沒有被鎖」放進「讀權威狀態、別看畫面猜」的通用診斷紀律裡。
• 延伸閱讀：鎖屏的視覺配置（背景、輸入框、時鐘 label）見配色系統、鎖屏與 GTK 主題的 Hyprlock 段；桌面故障恢復流程見常見故障場景與恢復操作。持鎖的那個 compositor 到底是什麼、還握著哪些系統狀態，見 Compositor 術語卡。

邊界條件

正常認證解鎖（走 unlock_and_destroy）後鎖屏 client 結束，compositor 已回到非鎖定狀態，不觸發失效保護。失效保護只在「持鎖中非正常結束」時出現。

Sway/swaylock 在 client 死掉時沒有畫面上的恢復提示（不像 Hyprland 會印指令），得預先知道走 TTY 或 SSH 執行 restore。「鎖是 compositor 持有、解鎖要認證」是 ext-session-lock 協議層的共通約束；失效保護的具體呈現方式因 compositor 而異。

fc-* 工具分工

fontconfig 附帶一組命令列工具，各自負責一件事：

fc-list 和 fc-match 每次執行都是新 process，讀到的是當下最新的系統快取。這跟已啟動的長駐程式不同——長駐程式的字型清單是啟動時的快照，詳見 font-availability-at-startup。

1fc-list | grep -i meslo
2# 確認 MesloLGS Nerd Font 有沒有裝、實際字族名是什麼
3
4fc-match "MesloLGS Nerd Font"
5# 查 config 裡寫的名字會匹配到哪支字型檔
6
7fc-match ":lang=zh-tw"
8# 查系統有沒有可用的繁體中文字型

Fallback chain

應用程式在 config 裡指定字族名（如 MesloLGS Nerd Font），fontconfig 依以下順序處理：

1. 在已知字型中找完全匹配的字族
2. 找不到就沿 fallback chain 往下找候選——fontconfig 的預設 fallback 規則定義在 /etc/fonts/conf.d/ 的 XML 設定檔中
3. CJK fallback 依語言優先序決定——fc-match ":lang=zh-tw" 回的是 fontconfig 認為最適合該語言的字型

Nerd Font（MesloLGS、JetBrainsMono 等）只含 Latin 字元與圖示 glyph，CJK 字元靠 fallback 到另一支字型（如 noto-fonts-cjk）補齊。fontconfig 的 fallback 對應用程式透明——應用程式只指定主字型，缺字時 fontconfig 自動補。

系統快取

fontconfig 把字型目錄的掃描結果存成快取檔，避免每次查詢都重新掃描整個檔案系統：

• 系統層快取：/var/cache/fontconfig/
• 使用者層快取：~/.cache/fontconfig/

套件管理器安裝字型時，post-install hook 會自動執行 fc-cache 更新系統快取（pacman 安裝完會印 Updating fontconfig cache）。手動把字型檔放進 ~/.local/share/fonts/ 時需要自己跑 fc-cache——不跑的話 fontconfig 看不到新字型。

fc-cache -f 的 -f 是 force，忽略時間戳全部重建；不加 -f 只更新有變動的目錄。兩者都只動系統快取層——已啟動的 process 記憶體中的字型清單不受影響，那是另一個層級的問題（見 font-availability-at-startup）。

下一步路由

• 字型安裝方式：終端機與編輯器的字型管理段
• 裝了字型但應用程式還是看不到：font-availability-at-startup（process 啟動時快照的時序問題）