Hazelnut 安裝設定教學：從下載到常駐，讓辦公室下載夾自己歸位

早上收的會議記錄、客戶傳來的報價單、要改的簡報、活動照片、剛裝完的安裝檔，到了下午全擠在下載夾。Hazelnut 做的事很單純：你先訂好規則，它就照規則把檔案搬到對的資料夾；開了常駐之後，新檔案一進來就自動歸位。

影片裡看的是效果，這篇把完整做法一步一步寫下來：先確認你的電腦能做到哪裡，再安裝、寫設定檔、檢查、預覽、真的搬，最後開常駐。下面的設定檔與指令都實際跑過（Hazelnut 0.3.0，Linux）。

先看你的電腦能做到哪裡

使用前要知道的條件：

• 它是終端機工具，規則寫在一個文字設定檔裡，沒有拖拉式的設定畫面。
• 它只看檔名、副檔名、大小、日期這類條件，不會打開檔案看內容，也不是 AI。報價單要靠副檔名或檔名規則來分，不是靠它「看懂」。
• 第一次設定建議請懂電腦的同事一起弄，先拿副本資料夾試。

步驟一：安裝

macOS（官方建議，預先編譯好、最快）：

brew install ricardodantas/tap/hazelnut

Linux：

brew install ricardodantas/tap/hazelnut   # 有 Homebrew 的話
cargo install hazelnut                    # 或用 Rust 的 cargo
pacman -S hazelnut                        # Arch Linux

Windows：

cargo install hazelnut

或到 https://github.com/ricardodantas/hazelnut/releases 下載預先編譯好的執行檔。

用 cargo 安裝需要 Rust 工具鏈，沒有的話先到 https://rustup.rs 照指示安裝。本篇在 Linux 用最精簡的 Rust 安裝後，直接從原始碼安裝（git clone 專案後在資料夾裡跑 cargo install --path .），約 52 秒裝好。

裝完確認版本：

hazelnut --version   # 本篇：hazelnut 0.3.0

步驟二：寫設定檔

設定檔放在 ~/.config/hazelnut/config.toml，先建資料夾，再用任何文字編輯器開新檔：

mkdir -p ~/.config/hazelnut

設定檔分兩部分，兩個都要有：

1. 盯哪個資料夾（[[watch]]）：官方特別提醒，只寫規則、沒寫監看資料夾，什麼事都不會發生。
2. 什麼檔案搬去哪（[[rule]]）：每條規則有「條件」和「動作」。

下面是本篇實際使用、檢查通過的辦公室設定，四條規則：文件、簡報、照片、安裝檔各有去處。

# 1. 盯哪個資料夾
[[watch]]
path = "~/Downloads"

# 2. 什麼檔案搬去哪
[[rule]]
name = "文件"
[rule.condition]
extensions = ["pdf", "docx", "xlsx"]
[rule.action]
type = "move"
destination = "~/Documents/文件"
create_destination = true

[[rule]]
name = "簡報"
[rule.condition]
extensions = ["pptx", "key"]
[rule.action]
type = "move"
destination = "~/Documents/簡報"
create_destination = true

[[rule]]
name = "照片"
[rule.condition]
extensions = ["jpg", "png", "heic"]
[rule.action]
type = "move"
destination = "~/Pictures/照片"
create_destination = true

[[rule]]
name = "安裝檔"
[rule.condition]
extensions = ["dmg", "pkg", "exe"]
[rule.action]
type = "move"
destination = "~/安裝檔"
create_destination = true

幾個欄位的意思：

• extensions：副檔名清單，符合其中一個就算。大小寫都認得（早上的測試裡，大寫的 .PDF 也符合 pdf 規則）。
• type = "move"：只搬不刪。
• destination：搬去哪；~ 代表你的家目錄。
• create_destination = true：目的地資料夾不存在就自動建立。
• 沒寫 overwrite 就是預設不覆蓋：目的地已有同名檔案時，不會蓋掉原本那份。

設定檔不在預設位置（例如 Windows），可以用 -c 指定路徑，例如 hazelnut -c 設定檔路徑 check。

步驟三：檢查設定有沒有寫錯

hazelnut check

看到 ✓ Config is valid，加上「幾個監看資料夾、幾條規則」，就代表格式沒問題。本篇是 1 個監看資料夾、4 條規則：

步驟四：先預覽，不會動到任何檔案

hazelnut run -d ~/Downloads

run 預設只是預覽：它會列出每個檔案打算搬去哪，但一個都不搬。本篇下載夾放了 10 個辦公室檔案，預覽列出每個檔案的目的地後，下載夾還是 10 個（下圖為了好讀，把輸出整理成「檔名　目的地」）：

這一步請一定要看過：確認報價單去文件、照片去照片夾，沒有搬錯，再往下。

步驟五：確認沒問題，真的搬

hazelnut run -d ~/Downloads --apply

加上 --apply 才會真的動手。本篇執行後下載夾剩 0 個，10 個檔案全部進了對應的資料夾：

步驟六：開常駐，之後全自動（Mac、Linux）

hazelnutd start     # 開始常駐
hazelnutd status    # 看有沒有在跑
hazelnutd reload    # 改完設定檔後重新載入
hazelnutd stop      # 停止

本篇開了常駐後，丟進一份報價單和一份簡報，三秒後下載夾剩 0 個，兩個檔案分別出現在文件和簡報資料夾：

Windows 沒有 hazelnutd，需要整理時自己跑一次步驟五的 hazelnut run -d 下載夾路徑 --apply。

實際用會遇到的狀況

• 同名檔案不會覆蓋：目的地已經有同名檔時，新的那份會留在下載夾，原本那份沒被蓋掉，畫面會出現 Destination exists and overwrite is false。同一批其他檔案照常搬走，只是指令最後會回報錯誤。留下來的那份請自己改名再搬。
• 沒寫規則的類型原地不動：例如 .txt 沒有對應規則，就留在下載夾。想整理就再加一條規則。
• 一個檔案符合兩條規則要小心：早上的測試讓一張截圖同時符合「截圖」和「照片」兩條規則，第一條搬走之後，第二條找不到檔案，整批中斷。解法是同一類檔案只安排一個去處，或在優先的那條規則的 name 下一行加上 stop_processing = true（寫在 [rule.condition] 之前），符合後就不再往下比對。
• Linux 全新帳號開不了常駐：家目錄下沒有 ~/.local/share 時，hazelnutd start 看起來有啟動，實際上沒有在運作。先執行 mkdir -p ~/.local/share 再啟動就正常。
• 動作請用 move，不要用 delete：官方也支援刪除類動作，但刪除是直接刪掉、不會進垃圾桶。辦公室用請一律只搬不刪。
• 先用副本試：第一次設定拿一個複製出來的資料夾當監看目標，確認規則沒問題，再換成真正的下載夾。

本篇沒測到的

macOS、Windows、互動介面（直接打 hazelnut 進入的終端機畫面）、桌面通知、丟垃圾桶的動作，以及大量檔案的情況。上面標「依官方說明」的部分，以官方 README 為準。

結論

下載夾天天要手動拖檔的辦公室，花一次時間把規則訂好就值得：之後新檔案自己歸位，同名檔也不會被蓋掉。它不會看懂檔案內容，所以規則要用副檔名或檔名來寫；Windows 沒有常駐，只能手動跑。

專案：https://github.com/ricardodantas/hazelnut （授權 GPL-3.0）

測試設備：Mac mini M4 Pro（12 核、64GB）。內容依實際執行結果撰寫，數據為撰寫當時的實測值。