本文用「桌面環境」泛指使用者看到的圖形介面整體。技術上，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 需要重開機。日常使用中遇到的故障多數落在前三層。

場景一：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）。

journalctl：系統日誌的主要入口

systemd 的日誌系統（journal）集中收錄所有 service、kernel、user session 的 log。journalctl 是查詢這些日誌的指令。

基本用法

 1# 本次開機的所有日誌
 2journalctl -b
 3
 4# 本次開機的錯誤以上等級（err + crit + alert + emerg）
 5journalctl -b -p err
 6
 7# 本次開機，只看最後 50 行
 8journalctl -b -n 50
 9
10# 上一次開機的日誌（如果問題發生在上次開機、這次重開後想查）
11journalctl -b -1
12
13# 即時跟蹤新 log（類似 tail -f）
14journalctl -f

過濾特定來源

 1# 只看 Hyprland 相關
 2journalctl -b | grep -i hypr
 3
 4# 只看特定 systemd user unit
 5journalctl --user -u waybar -b
 6
 7# 只看 kernel 訊息（等同 dmesg）
 8journalctl -b -k
 9
10# 只看某個 process 的 log（用 PID）
11journalctl _PID=12345

時間範圍過濾

1# 最近 10 分鐘的 log
2journalctl --since "10 min ago"
3
4# 指定時間區間
5journalctl --since "2026-06-30 14:00" --until "2026-06-30 14:30"

dmesg：Kernel 層訊息

dmesg 顯示 kernel ring buffer 的內容——硬體偵測、driver 載入、硬體錯誤這些 kernel 層面的事件。排查 GPU driver 問題、USB 裝置問題、磁碟錯誤時需要看這裡。

 1# 所有 kernel 訊息（帶時間戳記）
 2dmesg -T
 3
 4# 只看錯誤和警告
 5dmesg -T --level=err,warn
 6
 7# GPU 相關（NVIDIA）
 8dmesg -T | grep -i nvidia
 9
10# GPU 相關（AMD）
11dmesg -T | grep -i amdgpu
12
13# USB 相關（鍵盤滑鼠突然不回應時看這裡）
14dmesg -T | grep -i usb

GPU driver 問題在 dmesg 裡的嚴重度差異很大：

一般 GPU hang（driver 嘗試自動恢復）：

1[  123.456] nvidia-modeset: ERROR: ...
2[  123.789] NVRM: Xid (PCI:0000:01:00): 79, pid=1234, ...
3[  124.000] amdgpu: GPU reset begin!
4[  124.500] amdgpu: GPU reset succeeded

NVIDIA 的 Xid 錯誤代碼表示不同類型的 GPU 錯誤。常見的 Xid 79 是 GPU fallback，Xid 31 是 GPU setup failure。完整代碼表可在 NVIDIA 官方文件搜尋「Xid Errors」。

硬體層級故障（嚴重，可能需要檢查硬體）：

1[  123.789] NVRM: Xid (PCI:0000:01:00): 79, pid=1234, GPU has fallen off the bus

GPU has fallen off the bus 表示 GPU 跟主機板的 PCIe 連線完全中斷。偶發一次可能是 driver 問題，反覆出現通常是硬體故障（PCIe 供電不足、顯卡接觸不良、過熱）。

hyprctl：Hyprland 的 Runtime 狀態查詢

hyprctl 是 Hyprland 提供的命令列控制工具，可以在 compositor 運行中查詢狀態和執行操作。只有在 Hyprland 正在跑的時候才能使用。

 1# 目前所有視窗的資訊
 2hyprctl clients
 3
 4# 目前的 monitor 設定
 5hyprctl monitors
 6
 7# 目前的 workspace 資訊
 8hyprctl workspaces
 9
10# Hyprland 版本和 build 資訊
11hyprctl version
12
13# 重新載入 config（不重啟 compositor）
14hyprctl reload
15
16# 查看上一次 config reload 是否有錯誤
17hyprctl systeminfo

hyprctl reload 是測試 config 變更的安全方式。如果 config 有語法錯誤，reload 會報錯但 compositor 繼續用舊 config 跑，不會崩潰。

systemctl：Service 狀態管理

桌面環境的工具（waybar、mako 等）如果用 systemd user unit 管理，可以用 systemctl --user 查看狀態和重啟。

 1# 查看某個 user service 的狀態
 2systemctl --user status waybar
 3
 4# 輸出範例：
 5# waybar.service - Highly customizable Wayland bar
 6#    Loaded: loaded (/usr/lib/systemd/user/waybar.service; enabled)
 7#    Active: active (running) since Mon 2026-06-30 10:00:00 CST
 8#    Main PID: 1234 (waybar)
 9
10# 重啟
11systemctl --user restart waybar
12
13# 看最近的 log
14systemctl --user status waybar -n 20

如果這些工具不是 systemd unit（在 Hyprland config 裡用 exec-once 啟動的），就不能用 systemctl 管理。改用 pgrep 和 kill：

1pgrep waybar      # 查看是否在跑
2killall waybar    # 停止
3waybar &          # 背景啟動

即時資源監控

排查效能問題和記憶體耗盡時，需要看即時的系統資源使用情況。

htop：互動式 process 監控。按 M 可以按記憶體用量排序，按 P 按 CPU 排序。找到佔用異常的 process 後按 F9 可以直接 kill。

btop：功能更豐富的替代品，顯示 CPU、記憶體、磁碟、網路的即時使用情況，圖形化介面比 htop 直觀。

1# 安裝
2sudo pacman -S btop    # Arch
3sudo apt install btop  # Debian/Ubuntu
4
5# 執行
6btop

nvidia-smi：NVIDIA GPU 的專屬監控工具。顯示 GPU 使用率、記憶體、溫度、跑在上面的 process。

1# 一次性查看
2nvidia-smi
3
4# 持續監控（每 2 秒更新）
5nvidia-smi -l 2

常見 Log Pattern 速查

排查流程

這篇是 Hyprland 桌面的具體日誌工具；背後「先讀權威狀態、不靠肉眼猜」的通用診斷心法（每種問題的權威來源、四步流程），見 Linux 除錯與診斷：診斷心法。遇到桌面環境問題時的判讀順序：

1. 判斷影響範圍：只有一個視窗壞了、某個工具壞了、整個桌面壞了、還是系統完全不回應？影響範圍決定要看哪一層的 log。

2. 看 journalctl：journalctl -b -p err 先看本次開機有沒有錯誤等級的訊息。大部分 userspace 的問題（compositor crash、工具 crash）會出現在這裡。

3. 看 dmesg：如果 journalctl 沒有明顯線索、或症狀跟硬體有關（畫面凍結、USB 不回應），dmesg -T --level=err,warn 看 kernel 層有沒有硬體或 driver 錯誤。

4. 查特定工具的狀態：systemctl --user status <tool> 或 pgrep <tool> 確認工具是否還活著。如果死了，看它最後的 log 訊息。

5. 即時監控：如果問題是漸進式的（越來越慢、偶爾卡頓），開 btop 或 htop 觀察 CPU 和記憶體的即時趨勢，找出佔用異常的 process。

找到問題後的下一步

判讀完 log 確認問題類型後，行動路徑依問題性質分流：

• Config 錯誤：直接修 config，用 hyprctl reload 或重啟工具驗證。操作步驟見常見故障場景與恢復操作。
• 軟體 bug（segfault、特定操作觸發 crash）：到該軟體的 issue tracker（通常在 GitHub）搜尋錯誤訊息。Hyprland 的 issue tracker 在 github.com/hyprwm/Hyprland。回報 bug 時附上 hyprctl systeminfo 的輸出和相關的 journalctl log。
• GPU driver 問題：NVIDIA 用戶檢查是否有更新的 driver 版本（pacman -Syu nvidia）。AMD 用戶的 driver 跟 kernel 綁定，更新 kernel 就更新 driver（pacman -Syu linux）。
• 硬體故障（GPU has fallen off the bus 反覆出現）：軟體層面無法解決，需要檢查硬體（PCIe 插槽接觸、供電、溫度）。

第一步：分「連不到」還是「連得到但被拒」

錯誤訊息本身就能分層，不用猜：

• 訊息提到主機名解不出、連線逾時、retrieving file 失敗 → 連不到，往網路 / DNS / mirror 查。
• 訊息提到 database lock、signature、trust、conflicting、partial → 連得到、封包也拿到了，是套件管理器的狀態問題。

判準是問一句：「它到底有沒有成功連上 mirror？」有連上才談得到簽章、相依、db 狀態；連都沒連上，那些都還輪不到。剛裝好的最小系統最常見的是前者——網路設定還沒到位。

連不到那層：從實體介面往上查到域名

網路不通有好幾層，從最底層往上逐層確認，哪一層斷了一目了然。這條鏈跟最小安裝後的驗證裡的網路檢查同源，這裡聚焦在「抓套件失敗」這個症狀上：

1ip -brief a              # 1. 有沒有拿到 IP？介面 UP 且有位址
2ping -c1 8.8.8.8         # 2. IP 層對外通不通？（直接打 IP、跳過 DNS）
3getent hosts archlinux.org   # 3. 域名解得出來嗎？
4timedatectl              # 4. 時間對嗎？（影響下一層的簽章驗證）

第 2 步通、第 3 步不通 = DNS 問題，這是最小安裝最典型的落點：IP 層明明通（ping 8.8.8.8 有回應），但域名解不出來，因為 /etc/resolv.conf 還沒設 nameserver。這時 pacman 會卡在解析 mirror 主機名。修法是給系統一個 resolver——臨時可直接寫 /etc/resolv.conf（nameserver 1.1.1.1）。先看它是什麼（ls -l /etc/resolv.conf）：啟用了 systemd-resolved 或 NetworkManager 的系統上它是那些服務管理的 symlink，手寫會被覆蓋，治本要透過該網路管理服務設定 DNS；裸 Arch 最小安裝若沒啟用這些服務，它通常就是一個普通檔案，手寫即持久生效。

mirror 逾時 / 抓不到：DNS 通了、但某個 mirror 慢或掛了。換 /etc/pacman.d/mirrorlist 到地理近且快的鏡像（實測不同 mirror 速度可差數倍）。這也接回安裝選項判讀裡選 mirror 的決策——裝機當下選錯 mirror，這裡就會慢。

連得到但被拒那層：pacman 自己的狀態

連上 mirror、封包也拿到了卻失敗，問題在 pacman 的本地狀態或簽章驗證。這幾種各有明確徵兆與修法：

database lock：上次沒清乾淨的殘留

error: failed to init transaction (unable to lock database)。pacman 用 /var/lib/pacman/db.lck 這個鎖檔保證同時只有一個 pacman 在動資料庫；上次 pacman 被中斷（斷電、Ctrl+C、當掉）沒清掉鎖檔就會殘留。先確認真的沒有 pacman 在跑（pgrep -x pacman），確認沒有再刪鎖檔：

1pgrep -x pacman && echo "有 pacman 在跑、別刪" || sudo rm /var/lib/pacman/db.lck

先查再刪這個順序重要——盲刪鎖檔時如果真的有另一個 pacman 在跑，兩個同時寫資料庫會弄壞它。

簽章 / keyring 過期：十之八九是時間不對

invalid or corrupted package (PGP signature) 或 signature is unknown trust。pacman 驗證每個套件的 GPG 簽章，驗證失敗最常見的根因是系統時間不對——這正是第一步要 timedatectl 的原因。時間差太多（新裝的 VM、主機板電池沒電的老機器）會讓「簽章的有效期」判斷錯誤，明明有效的簽章被判過期。先校時：

1sudo timedatectl set-ntp true     # 開 NTP 自動校時（SSH 進最小系統無 polkit 互動代理、裸跑會被拒，要 sudo）

時間對了還失敗，才是 keyring 本身的問題（archlinux-keyring 太舊）：sudo pacman -Sy archlinux-keyring 更新 keyring，必要時 sudo pacman-key --refresh-keys。順序是先校時再動 keyring，因為時間不對時連 keyring 都更新不了。

partial upgrade：只同步不升級造成的相依斷裂

conflicting dependencies 或裝完某個套件後系統行為異常。根因是在 rolling 發行版上只做了 pacman -Sy（同步資料庫）就裝新套件，卻沒 -u（升級既有套件）——新套件依賴新版函式庫，但系統還是舊的，相依對不上。Arch 只支援 full upgrade：一律 pacman -Syu，永遠不要單獨 -Sy 之後裝東西。這條規則救掉這一整類故障。

stale db 404：裝機當下的資料庫已經過期

error: failed retrieving file '...' 404，而且換好幾個 mirror 都一樣。這是 rolling 發行版特有的時序陷阱：Arch 的 mirror 不保留舊版檔案，你裝機時 ISO 內建的套件資料庫指向的檔名，可能幾天內就被輪替掉了——資料庫說有這個檔、mirror 上已經沒有。修法跟上一條同源：pacman -Syu 先把資料庫同步到最新，檔名對上了就抓得到。這也是為什麼「一律 -Syu」是 Arch 的鐵律，而不只是建議。

判讀總表

下一步

• 這幾步用到的網路驗證，完整版在最小安裝後的工具驗證與補足。
• 裝機時選 mirror / locale / 時區的決策，見Linux 安裝選項判讀。
• 跨發行版時「這個套件名 / 這個旗標在別的發行版叫什麼」的差異判讀，見平台與發行版差異的判讀地圖。
• 套件抓下來了、但 bootstrap 腳本本身失敗要 debug，見可除錯的 bootstrap。
• 系統跑起來後才出的套件問題（AUR 建置失敗、-bin 包 soname 斷裂等），屬除錯範疇，見Linux 除錯與診斷。

Linux 桌面環境跟 Windows 在故障模型上有根本的結構差異。Windows 的藍屏（BSOD）是核心層崩潰，整台機器停擺；Linux 桌面環境的大部分故障只影響 userspace，系統核心不受波及。理解這個隔離邊界，是判斷「當下該做什麼」的前提。

這個模組的閱讀方式跟其他模組不同。其他模組是線性學習——從頭讀到尾建立知識。這個模組是 reference——出問題時根據症狀查對應的恢復操作。第一篇建立概念模型，第二篇按場景查操作，第三篇教怎麼看日誌找根因。

章節文章

跨分類引用

• -> 模組五：Hyprland 配置：Hyprland 的配置結構和 hyprctl 指令
• -> 模組六：桌面 Rice 設計：waybar / wofi / mako 等工具的配置位置
• -> 模組八：同步、Bootstrap 與環境重建：環境損壞到無法修復時的重建策略

具體錯誤訊息對照表（「address already in use 要這樣修」「model not found 要那樣修」）不在本章——這些隨工具版本變、查 release notes 跟 GitHub issue 更快。本章寫的是「換工具之後仍成立」的排錯思維。

本章目標

讀完本章後、你應該能：

1. 看到症狀時、先定位是介面 / 伺服器 / 模型哪一層的問題。
2. 知道在每一層該看什麼 log。
3. 用「最小可重現」策略快速縮減問題範圍。
4. 識別「跨層級的誤判」常見模式、把 server 層問題正確歸位、避開瞎調 model 的繞路。

故障定位的核心原則：先確認哪一層壞

模組零 三層架構 的視角延伸到排錯：故障可能落在介面層（Continue.dev / Cursor 等 IDE 整合）、伺服器層（Ollama / LM Studio / llama.cpp）、或模型層（權重檔本身的能力 / 量化選擇）。在不知道哪一層壞之前、任何修法都是亂槍打鳥——重啟 Continue.dev 解不了模型量化太激進的問題、重 pull 模型解不了 IDE 設定錯的問題。

先定位再修補的 ROI 高於直接修補、因為沒有定位的修法常常掃過正確答案還不知道是哪個動作生效。定位用的工具不複雜：

• 直接 curl 伺服器 API：繞過介面層、直接驗證伺服器是否回應正常。
• ollama ps / 等價指令：看伺服器層 model 狀態、確認 model 真的載入。
• 換 model 試試：同樣 prompt、不同 model 表現一致就是介面 / 伺服器層、不一致就是 model 層。
• 換 prompt 試試：簡單 prompt OK、複雜 prompt 崩、可能是 context 長度或 model 容量問題。

這四個動作能 cover 90% 的定位需求。學會這個反射、排錯時間大幅縮短。

症狀到層級的對應反射

不同症狀對應到不同最有可能的故障層、建立對應反射能省下大量試錯時間。下表是寫 code 場景常見症狀的對應：

對應的具體驗證指令範例：

• 回答亂碼 / 重複：ollama list 確認當前 model tag、改跑 ollama run <較高量化版本>（例如 Q4 → Q5）；同 prompt 換 model 確認是不是 model 本身能力問題、不是伺服器。
• TTFT 異常變長：ollama ps 看 model 是否被 unload 又重載（keep_alive 太短）；檢查 prompt 字數是否暴增（10K+ tokens 進入 prefill 痛點區）。
• Ollama 自己 crash：launchd service 模式看 /opt/homebrew/var/log/ollama.log、前景模式看啟動 terminal 的 stderr。

這張表的核心訊號：

• 「沒回應」「connection 系」→ 通常 server 層。
• 「內容怪」「答非所問」「重複」→ 通常 model 層。
• 「設定怪」「快捷鍵不對」→ 通常介面層。
• 「整機卡」→ 系統資源、不一定哪層的「bug」、可能是規格不夠。

把這個 mapping 內化、看症狀立刻有第一手猜測、不用每次從零思考。

Log 在三層的角色差異

每一層的 log 看的東西不同、用法不同：

介面層 log

• 位置：IDE plugin 的 console（VS Code Developer Tools、JetBrains 的 plugin log）。
• 看什麼：請求是否發出、發到哪個 endpoint、回應 status code、parse error。
• 常見訊號：請求根本沒發 → 介面層配置錯；請求發了但伺服器拒 → 伺服器層；請求成功但 parse 失敗 → 介面層或伺服器層回應格式不對。

伺服器層 log

• 位置：Ollama 在 ~/.ollama/logs/server.log 或類似位置、LM Studio 在 console 輸出、llama.cpp 在啟動 terminal。
• 看什麼：模型載入過程、推論進度、error trace、記憶體狀態。
• 常見訊號：載入 model 卡住 / 失敗 → model file 損壞或記憶體不足；推論時 OOM → 量化太激進或 context 太長；連線錯誤 → port 配置或 host binding。

模型層的觀察訊號

模型層通常沒有獨立的 log——權重檔本身不會 log、行為要透過伺服器層觀察。判讀模型問題的訊號通常是：

• 「載入成功、推論時崩」→ 量化等級或記憶體配對問題。
• 「載入成功、推論結果差」→ 模型能力或量化品質問題。
• 「不同 prompt 表現不一致」→ 可能是 model 對特定 pattern 弱、不是 bug。

模型層問題多半不是「壞了」、是「能力上限」——換更大模型或調量化是主要解法、不是「修 bug」。

log level 預設夠用、針對性提升

實務上 default log level 提供的訊息已涵蓋多數排錯需要；全部開 verbose 反而把 noise 蓋過 signal、要找的關鍵錯誤被淹沒。有問題時針對該層提升 log level（其他層保持 default）、定位完再降回來。

最小可重現的縮減策略

症狀複雜時、把問題縮到最小、再逐步加回來。這個方法在所有軟體 debug 都通用、套用到 LLM 場景的具體流程：

1. 直接 curl 伺服器、用最簡 prompt 復現：

   • 繞過介面層、確認伺服器本身行為。
   • prompt 用 "Hello" 這種最短的、排除 prompt 複雜度因素。
   • 如果這步就崩 → 伺服器 / 模型層問題、可以排除介面層。

2. 換不同 model 試：

   • 同樣 prompt、換 gemma4:e4b 或 llama3.2:1b。
   • 不同 model 都正常 → 原 model 問題。
   • 不同 model 也崩 → 伺服器層問題。

3. 換不同伺服器試：

   • Ollama 接不上、用 LM Studio 同模型試。
   • 兩個都崩 → 模型或系統層問題。
   • 一個好一個壞 → 該伺服器特有問題。

4. 改變一個變數一次：

   • 每次只改一個變數（設定 / model / IDE 重啟三選一）、確保行為變化能對應到具體動作。
   • 每次只改一項、觀察行為變化。

5. 記錄每一步：

   • 排錯 30 分鐘還沒解時、開始會忘記試過什麼。
   • 簡單 notebook 記錄「改了什麼、行為怎麼變」、避免轉圈。

這個方法看起來慢、實際上比「亂試一通」快很多。亂試的代價是「以為改了 A 沒效、其實改 A 跟改 B 互相抵銷、不知道」。最小可重現是 disciplined approach、值得花時間建立習慣。

跨層級的常見誤判

排錯時常踩的陷阱是「把某層的問題誤判成另一層」、修錯方向白費力氣。常見誤判模式：

把伺服器問題誤當模型問題

例：Ollama 因為 port 被佔啟動失敗、IDE 看到 connection refused、誤以為「model 載不起來、需要換 model」。實際上換 model 也救不了、要看 server log 才知道是 port 問題。

判讀：connection 系問題 → server 層、不是 model 層。

把模型問題誤當伺服器問題

例：用 Q3 量化跑 7B 模型、輸出全是亂碼、誤以為「Ollama bug」、開 issue 報。實際上是量化太激進、模型本身輸出崩、換 Q4 就好。

判讀：「server 看起來正常、輸出怪」→ 通常 model 層、改量化或換 model。

把介面問題誤當伺服器問題

例：Continue.dev 的 config.json 寫錯 apiBase、IDE 顯示 connection error、誤以為「Ollama 掛了」。實際上 Ollama 正常、curl 過得去、IDE 配置錯。

判讀：curl 過得去、IDE 過不去 → 介面層配置問題。

把系統資源問題誤當軟體 bug

例：32GB Mac 跑 31B + 同時開大量 app、Mac 整體變慢、誤以為「Ollama 越來越慢」。實際上是記憶體 swap、Ollama 沒問題。

判讀：Activity Monitor 看 Memory Pressure 變紅 / swap 大量、是系統資源、不是軟體 bug。

把 prompt 問題誤當模型問題

例：給 model 超長 context（30K token）、TTFT 30 秒、誤以為「model 變慢了」。實際上是 prefill 階段需要時間、跟 model 沒變慢無關。

判讀：短 prompt 正常、長 prompt 慢 → prefill 問題、可預期、不是 bug。

每種誤判的根因都是「症狀對應到錯的層級」。內化「症狀 → 層級」對應反射、能避開多數誤判。

排錯工具箱

四個基本工具能 cover 90% 的排錯場景：

curl

• 角色：直接打伺服器 API、繞過介面層。
• 用法：curl http://localhost:11434/api/version 看伺服器是否回應、curl http://localhost:11434/v1/chat/completions 帶最簡 prompt 試完整流程（11434 是 Ollama 預設 port、見 1.0 Ollama）。
• 價值：排除介面層、確認伺服器層行為。

ollama ps / 等價指令

• 角色：看伺服器層當前 model 狀態。
• 用法：ollama ps 列出載入記憶體的 model、看 size、idle timer。
• 價值：確認「我以為載入了」跟「真的載入了」是否一致；看記憶體佔用是否合理。

Activity Monitor / system monitor

• 角色：看系統資源狀態。
• 用法：Memory Pressure 是否變紅、CPU / GPU 使用率、swap 量、過熱降頻。
• 價值：區分「軟體 bug」跟「規格不夠」。多數本地 LLM 慢的問題是規格、不是 bug。

IDE 開發者工具

• 角色：看介面層請求 / 回應。
• 用法：VS Code 的 Help → Toggle Developer Tools、看 Network tab、看 Console。
• 價值：確認介面層真的把請求發出去、看 server 回什麼。

這四個工具學會用、寫 code 場景 90% 的排錯都能處理。剩 10% 的 deep issue（如 driver 問題、模型權重檔損壞、framework 內部 bug）需要更專業的工具、但這 10% 對寫 code 使用者來說、通常該求助社群或回報 maintainer、不是自己 debug。

排錯流程的決策樹

把上面的內容整合成一個流程：

 1症狀出現
 2  ↓
 3curl 伺服器（伺服器層活著嗎）
 4  ├─ curl 失敗 → 看 server log（伺服器層問題）
 5  │   ├─ port 衝突 → 改 port 或 kill 舊 instance
 6  │   ├─ model 載入失敗 → 看 file / 記憶體
 7  │   └─ crash → bug report、看版本是否最新
 8  └─ curl 成功 → 介面層或 model 層問題
 9      ↓
10      換最簡 prompt 試（model 在簡單 prompt 上正常嗎）
11      ├─ 簡單 prompt 也崩 → model 層問題
12      │   ├─ 換 model 試 → 不同 model 都崩 → 系統或伺服器
13      │   └─ 同 model 換量化等級 → 量化太激進
14      └─ 簡單 prompt OK、複雜 prompt 崩
15          ↓
16          看 prompt 長度跟 context 限制
17          ├─ context 超出 → 縮短 prompt 或換 long-context model
18          └─ context 在範圍內 → model 能力上限、考慮換大 model
19              ↓
20              （如果伺服器、prompt、model 都檢查過還是壞）
21              介面層配置問題
22              ├─ 看 IDE plugin developer console
23              ├─ 比對 config.json 跟最簡 working example
24              └─ reset 設定後重試

這棵樹不是「按順序跑完」、是「定位後對應到具體分支」。學會用症狀直接 jump 到對應分支、不必每次從根跑起。

何時不適用本章方法論

本章「三層架構定位」假設「單機、單 user、單一伺服器實例、人在駕駛位」的個人開發場景。以下情境的方法論需要擴充：

本章方法論的甜蜜點是「個人 Mac、一個 IDE、一個 Ollama instance」的場景。離開這個甜蜜點、要把「三層」擴充成更多層（user / network / cluster）、或改用 production-grade 觀察工具。

何時過時 / 何時不過時

不會過時的部分：

• 三層架構視角排錯（介面 / 伺服器 / 模型）。
• 「先定位、再修補」的反射。
• 最小可重現的縮減策略。
• 五類跨層級誤判模式的識別。
• 四個基本工具的概念（curl / process status / system monitor / dev tools）。

會變的部分：

• 具體錯誤訊息文字（隨 Ollama / LM Studio / Continue.dev 版本變）。
• log 檔位置（隨工具更新可能調整）。
• 特定指令名稱（如 ollama ps 將來可能改名）。
• 特定工具的開發者面板路徑。

換工具或工具升級之後、本章的方法仍適用、只需要重新對應到「新工具的對應指令在哪」。看到新錯誤訊息時、回到三層架構定位、用最小可重現縮減——這比 google 錯誤訊息字面快得多、也比「重啟一次再試」可靠得多。

下一章

下一章：模組二 LLM 的數學基礎、或回到 模組一首頁 看其他章節。

一個 App 的真實佔用不等於它的 .app 大小

判斷一個 App 吃多少空間，要算的是它的總足跡（footprint），而不是 /Applications 裡那顆 .app 的大小。.app 只是程式本體，App 跑起來產生的資料（下載內容、快取、登入狀態、設定、日誌）絕大多數寫在 ~/Library 底下的好幾個不同位置，跟 .app 完全分家。

這台機器上最極端的例子是 Steam：它的 .app 只有 10.8M，但遊戲資料佔了 8.1G，兩者差了近 800 倍。只看 /Applications 的大小排序，Steam 會排在很後面，完全看不出它是全機第一大戶。同樣地，Amazon Kindle 的 .app 才 138M，書庫卻在沙箱容器裡佔了 3.2G。這就是為什麼「按目錄統計」和「按 App 統計」會給出完全不同的排行；要回答「哪個 App 該清」，必須把佔用聚合回 App。

佔用散落在 ~/Library 的哪些地方

聚合的第一步是知道一個 App 會把資料寫到哪些固定位置。下表只列與空間相關的主要位置（非 ~/Library 全量），macOS 對它們有約定，每個位置承擔不同責任，也決定了它能不能安全清掉。

這張表的關鍵分界是「快取」與「資料」。Caches 和 HTTPStorages 是純衍生物，清掉只是讓 App 下次重新下載或重建，最多重新登入一次，所以是回收空間時的首選。Application Support、Containers、Group Containers 則是使用者資料，Steam 的遊戲、Kindle 的書庫、聊天記錄都在這裡，刪了就真的沒了。Group Containers 還要多一層留意：它是同一個開發商旗下多個 App 共享的目錄，動它可能同時影響好幾個 App。

腳本對每個 App 把上面這些位置全部找出來、用 du 量實際佔用、加總成一個數字，再附上逐項明細，讓人一眼看出「這 4G 裡有多少是可清的快取、多少是動不得的資料」。

命名不一致是聚合的主要難點

把資料夾正確歸給某個 App 的難點在於：macOS 對這些目錄沒有統一的命名規則。有些 App 用它的 bundle id（例如 com.valvesoftware.steam）當目錄名，有些直接用 App 的顯示名稱（例如 Steam），同一個 App 的不同位置甚至各用一種。

腳本的做法是對每個 App 先讀出它的 bundle id，然後 Caches、Application Support、Logs 這幾個位置兩種命名都比對一次，bundle id 專屬的位置（Containers、HTTPStorages、Saved Application State）則用 bundle id 找。Group Containers 又是另一種格式，名稱前面多一段開發商的 team id（10 碼英數，像 ABCDE12345.group.com.foo），因此改用 bundle id 做子字串比對。這套規則涵蓋了絕大多數 App，但用罕見自訂命名的資料仍可能漏抓，這是聚合式估算的固有邊界，腳本在輸出裡據實標明「可能漏抓」而不假裝是精確值。

Homebrew 要分開算

透過 Homebrew 裝的工具不在 /Applications，需要獨立統計。佔用分兩類（概念詳見 Homebrew 知識卡）：命令列工具與函式庫（formula）在 Cellar/，GUI App 的下載 artifact 與 metadata（cask）在 Caskroom/。cask 安裝的 .app 本體實際放在 /Applications，已被前面的 App 聚合排行計入；Caskroom/ 存的是安裝來源與版本資訊，體積通常遠小於 App 本體，兩邊不重複計。

這台機器的 formula 前幾名是開發語言執行環境：dotnet@9 634M、兩個版本的 openjdk 合計 600M、mysql 292M、go 258M。formula 會多版本並存（例如 python@3.13 和 python@3.14 各算各的），所以腳本把整個 formula 目錄一起計。除了已安裝的部分，腳本還列出 brew --cache 的下載快取，以及 brew cleanup -n 預估可回收的舊版本（-n 是 dry-run，只報告不刪），跟整支腳本的唯讀原則一致。

聚合一律用 du 取實際佔用

App 各位置的聚合一律用 du -skx 取實際佔用，而不是 ls / find -size 的邏輯大小。sparse 檔（稀疏檔）只有寫入過的區塊才真正佔磁碟，宣告的邏輯大小可能是實際佔用的數十倍；容器與資料目錄裡正好常有 VM 映像、容器磁碟這類 sparse 檔，拿邏輯大小加總會把整份聚合排行灌水。完整的 sparse 踩坑案例見 disk-report 那篇。

-x 讓 du 不跨越檔案系統邊界，避免把掛載進來的卷重複計入；-k 統一用 KB 當單位，方便把各位置的數字加總後再換算成人類可讀的 G / M。

實測結果

下面是這台機器的實測排行（名次因個人使用習慣而異）；要看的是聚合排行和「按目錄統計」給的印象差多少：

全機掃到 65 個 App、聚合總計 48.2G。這份排行的價值在於它直接指向「該從哪裡下手」，而判讀邏輯可以套到任何人的排行上：本體小、資料大的 App（這台是 Steam、Kindle）要回收就得處理書庫與遊戲本身；純快取大的（這台是 Dia 的 1.6G）清掉零風險；本體就大的開發工具（Xcode、Android Studio）除非不再開發否則動不得。同一個總數字底下，可清的比例天差地別，這正是逐項明細要回答的問題。

聚合的邊界：總計不等於整機

這個 48.2G 是「能歸屬到已安裝 App 的部分」之和，不是 ~/Library 的全量。disk-report 那篇量到的 ~/Library 約 70G，差額落在幾類刻意不歸進單一 App 的位置。

最大的一塊是 ~/Library/Developer（這台約 5.5G，幾乎全是 Xcode 的 DerivedData、CoreSimulator 與 iOS DeviceSupport）。它們是 Xcode 與模擬器產生的共用產物，硬塞給 Xcode 會誇大這顆 App、塞給別人又不對，app-report 比照 Homebrew 把它單獨列成一段（app-report --dev）。也因為這樣，上面排行裡的 Xcode 只算到 .app 本體，它的建置產物要看 Developer 那段——這也是為什麼 disk-report 會把「Xcode DeviceSupport」列為大戶，而逐 App 排行卻看不到：那筆資料正住在這個不歸單一 App 的位置。

其餘排除的還有 iCloud 與雲端硬碟的本地鏡像（Mobile Documents、CloudStorage）、已移除 App 留下的孤兒資料夾、以及 Preferences。排行掃的是 /Applications、~/Applications、/Applications/Utilities 與 Setapp、Mac App Store 裝的 App；直接從 DMG 跑、沒搬進 Applications 的 App 不會出現在排行，但它的 ~/Library 資料若命名對得上仍可能部分計入。

還有一個方向相反的誤差要記得：這是估算不是精算。同一份資料若以 APFS clone 出現在多個被聚合的位置，逐位置分開跑 du 會各自計入（du 只在單次執行內對硬連結以 inode 去重，對 APFS clone 不去重），聚合值可能偏高。要看整個 ~/Library 到底多大、由誰佔，回到 disk-report 的逐層 du。

固化成 app-report 腳本

把這套聚合邏輯寫成腳本，往後想知道「誰在吃空間」就一行重跑，不必每次重想要比對哪些目錄、要怎麼處理命名差異。腳本和 disk-report 收在同一個公開 repo tarrragon/scripts 裡，維持「跟專案無關的系統工具放個人 bin」的一致做法。

兩支腳本在同一個 repo；若已為 disk-report clone 過 ~/Projects/scripts，跳過 clone、只做 symlink。首次安裝則把 repo clone 下來，再把腳本本體 symlink 到個人的 ~/.local/bin，這樣本機呼叫的永遠是 repo 的最新版：

1git clone https://github.com/tarrragon/scripts.git ~/Projects/scripts
2ln -s ~/Projects/scripts/app-report/app-report ~/.local/bin/app-report

PATH 設定同 disk-report（見 macOS 新機基礎建設）。裝好後直接呼叫：

1app-report           # 完整報告：App 聚合排行 + Developer + Homebrew
2app-report --apps    # 只看 App 聚合排行（預設前 30）
3app-report --apps 50 # 排行顯示前 50
4app-report --dev     # 只看 ~/Library/Developer 開發工具共用資料
5app-report --brew    # 只看 Homebrew

要清哪個 App，看完明細再動手：移掉 .app 並清對應的 ~/Library 資料夾（報告每個 App 下方列的路徑就是清除對象；先從 Caches / HTTPStorages 開始，確認再考慮資料目錄），Homebrew 用 brew cleanup -s。

兩支腳本的分工

disk-report 與 app-report 是磁碟清理的兩個接力棒。前者在卷與目錄層找出最大的子樹，通常落在 ~/Library；後者接手把那棵子樹拆到 App，看出具體是誰佔的、各自有多少是可清的快取。先 disk 找方向、再 app 定位到人，兩支都唯讀，回收的最後一步都留在人這一端。

最後把整套診斷固化成一個唯讀的 disk-report 腳本，往後同類情況可以一行指令重跑。

先確認問題是「真的滿」還是「浮動的假象」

排查磁碟的第一步是分辨空間到底去哪：是被真實檔案佔走，還是被系統的快照與 purgeable（系統可隨時回收的緩衝空間）暫時佔住。這兩者的處理方式完全不同，先分清楚才不會白清。

在 APFS（Apple File System，macOS 的預設檔案系統）上，根目錄 / 是唯讀的系統封印卷，真正存放使用者資料的是 /System/Volumes/Data，而它們和其他卷（Preboot、Recovery、VM、模擬器 runtime）共用同一個 container（容器，APFS 管理空間的最上層單位）的空間池。判斷「還剩多少」要看整個 container 的可用空間，而不是單一卷的數字。

1df -h /System/Volumes/Data
2diskutil info /System/Volumes/Data | grep -iE "Container Free Space|Container Total Space"

這次的結果是資料卷 100% 滿、整個 container 只剩約 591MB。確認確實滿載、不是顯示誤差，後面才值得花力氣找佔用大戶。

「空間掉了又回來」的根因：本地快照與 purgeable

空間在幾小時內反覆消長、清 cache 卻無效，最常見的原因是 Time Machine 的本地快照（local snapshots）加上 macOS 的 purgeable 空間，而不是某個看得見的檔案。這是排查時要先排除的一條線。

本地快照的運作方式是：Time Machine 啟用時，系統約每小時自動建立一張快照「凍結」當下狀態，好讓本地也能做時光機回溯。這些被凍結的資料，正是先前以為已刪除、卻怎麼清都不會釋放的空間。快照保留約 24 小時（Apple 的 thinning 策略，觀察值），或在磁碟空間壓力過大時提前清除；後者正是「過一陣子空間又回來」的來源。若從未設定 Time Machine，這條線可跳過——沒啟用就不會有 local snapshot。

1tmutil listlocalsnapshots /System/Volumes/Data

這次查的時候快照數是 0，但這不代表它不是元兇——恰恰相反，是磁碟已經滿到讓系統把快照全數清光了。判讀訊號是：若這個指令平常列出多筆快照、且磁碟空間在數字上頻繁浮動，浮動量就來自這裡，跟手動清的 cache 無關。根治方向是把總用量降下來、讓磁碟保有餘裕，系統就不會一直貼著上限狂建狂清快照。

purgeable 是同一條線的另一半，但它沒有好用的精確讀數。diskutil apfs list 能看 container 層的概況，而 purgeable 主要由快照與系統快取構成、本來就會自己浮動。處理方式跟快照一樣：把總用量降下來、讓系統在空間有壓力時自行釋放，而不是找指令直接清它。「沒有直接讀數」本身就是判讀邊界——看到可用空間和「實際檔案總和」對不上時，差額多半就在這塊浮動緩衝，不必懷疑是哪個檔案在搞鬼。

用實際佔用值找大戶，避開 sparse 假大小

找佔用大戶要用 du（實際佔用的磁碟區塊）排序，不能依賴 ls -l 顯示、或 find -size 篩選所用的邏輯大小。對一般檔案兩者相同，但對 sparse 檔（稀疏檔）差距可以是好幾十倍，誤判會追錯目標。

這次就踩到這個陷阱。find 列出近期修改的大檔時，OrbStack（一套容器與 VM 執行環境）的虛擬磁碟映像顯示為 228G，看起來像頭號兇手；但用 du 一量，實際佔用只有 1.9G。同樣地，macOS Podcasts 在 tmp 塞的一堆 .tmp.resize.img 顯示有數十個檔，實際只佔 3.5M。這些都是 sparse 檔：宣告了很大的邏輯大小，但只有寫入過的區塊才真正佔磁碟。

1# 實際佔用（正確）
2du -sh ~/some/large.img
3
4# 顯示大小（對 sparse 檔會嚴重高估，誤判用）
5ls -lh ~/some/large.img

定位順序是由外往內逐層收斂：先看家目錄前 20 大，鎖定最大的子樹（這次是 ~/Library 70G 左右），再往下展開 ~/Library/Application Support、~/Library/Containers，直到找到具體的檔案或目錄。

1du -shx ~/* ~/.[!.]* 2>/dev/null | sort -rh | head -20
2du -shx ~/Library/* 2>/dev/null | sort -rh | head -12

-x 讓 du 不跨越檔案系統邊界，避免把掛載進來的唯讀卷（例如 iOS 模擬器 runtime）重複計入；~/.[!.]* 這個寫法只展開以單一點開頭的隱藏檔，排除掉 . 和 .. 兩個會被一般 .* 誤抓進來、算出整個家目錄大小的假項目。

這次找到的佔用大戶與處理

定位出來的大戶集中在開發工具鏈與閒置的本地資料，多數可逆、刪了之後需要時會自動重建或可重新下載。下面的項目與數字都是這台機器的實測，換一台機器組成會完全不同；值得帶走的是每一項背後的判讀問題，不是這份清單本身。具體刪除指令因工具而異（Android Studio GUI、rm -rf、ollama rm），本文只做診斷與定位，刪除操作留給各工具自身的文件。以下逐項說明判讀依據。

Android NDK 的判讀要回到「誰在用它」：這次專案是 Flutter，NDK 版本由 flutter.ndkVersion 決定，而不是專案自己 pin。查當前 Flutter 要求的版本後發現，本機裝的兩版都是舊 Flutter 留下的殘留，於是保留較新的一版、刪掉最舊的。判斷可不可刪的關鍵是先確認「現在到底用哪版」，而不是看修改日期就動手。

Claude 桌面的 vm_bundles 是最大單一項目（11G）。它是桌面 App 的 Cowork 功能在本地沙箱 VM 裡執行程式用的根檔案系統映像。關鍵判讀是：它不是每次開 App 就重建——映像的修改日期停在數月前，是一次性佈建、之後沿用。只有實際使用 Cowork 沙箱時才會佈建和更新。所以對只用終端機 CLI、桌面 App 僅拿來聊天的人，這 11G 是純佔用，可以安全刪除；唯一後果是哪天實際開了 Cowork session，它會重新佈建。

剩下三項的判讀各有自己的關鍵問題。閒置的 AVD 與 system-image 是「一個 API 版本一組」的綁定，停用某個 Android 版本時要連 AVD 帶它依賴的系統映像一起刪，只刪一邊會留下半套。ollama 本地模型的判斷是「改用雲端後還會不會在本地跑」，閒置的大模型可刪，但小的 embedding 模型常被其他工具當依賴、刪了會牽連（ollama 模型的累積速度與專屬清理 idiom，見 本地 LLM 的資源管理）。Xcode 的 iOS DeviceSupport 則是實體裝置接線除錯時產生的符號快取，可以放心刪——下次接上同一台裝置除錯時 Xcode 會自動重建。

這幾項合計回收約 17G，可用空間從約 591MB 拉回到 18G，磁碟脫離滿載。

把診斷固化成 disk-report 腳本

一次性查完之後，把這套順序寫成腳本的價值是：下次同類情況不必重新回想指令與判讀順序，一行就能重跑，而且固定先看快照、再用實際佔用值，不會又掉進 sparse 假大小的陷阱。

腳本收在公開 repo tarrragon/scripts，而不是放進某個專案的 bin/。它跟任何專案無關，連到個人 bin 才能在任何地方直接呼叫，也不會污染專案 repo。安裝方式是 clone 下來、把腳本本體 symlink 到 ~/.local/bin：

1git clone https://github.com/tarrragon/scripts.git ~/Projects/scripts
2ln -s ~/Projects/scripts/disk-report/disk-report ~/.local/bin/disk-report

這一步預設 ~/.local/bin 已在 PATH 上。若還沒設定，做法見 macOS 新機基礎建設 的對應項目。腳本刻意設計成唯讀：只報告、不刪除，刪什麼由人看完報告再決定。

1disk-report              # 完整診斷：總覽 + 快照狀態 + 各層大戶 + 開發環境可清項
2disk-report --growing    # 只看過去 180 分鐘內長大的大檔（抓動態暴增最快）
3disk-report --growing 60 # 改成過去 60 分鐘

--growing 模式對應的是本文開頭那個「幾小時內暴增」的情境：當空間正在快速消失、想抓現行犯時，直接列出近期被寫入的大檔，比逐層 du 更快定位。

1find "$HOME" -type f -size +50M -mmin -180 2>/dev/null \
2  -exec du -h {} \; 2>/dev/null | sort -rh | head -25

50M 的下限是為了過濾日常小檔雜訊、鎖定單一大檔暴增；若懷疑是大量小檔累積吃空間（如快取碎片），這個門檻抓不到，要回逐層 du 看目錄總量。排序依據同樣是 du 的實際佔用值，而不是 find -size 的邏輯大小門檻，理由和前面一致：避免 sparse 檔的邏輯大小把排序帶歪。

排查順序總結

這次的方法可以收斂成一條固定順序，往後遇到任何「磁碟莫名變滿」都先照這條走：

1. 先看 container 可用空間，確認是真滿還是顯示誤差。
2. 再查本地快照與 purgeable，排除「掉了又回來」的浮動來源。
3. 用 du -shx 由外往內逐層找大戶，全程以實際佔用值判斷，不信 ls / find 的顯示大小。
4. 對每個大戶問「現在誰在用它」再決定刪不刪，可逆的優先清。
5. 把整套順序固化成唯讀腳本，下次一行重跑。

第 3 步若收斂到 ~/Library 這種多個 App 共用的大目錄，按目錄統計只能看出 Caches、Containers 各多大，看不出是哪幾個 App 佔的。把這棵子樹再按 App 拆開的做法，見 macOS App 聚合佔用報告。