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

- 網址：https://blog.valenvan.uk/posts/ricardodantas-hazelnut.html
- 發布日期：2026-10-25
- 測試設備：Mac mini M4 Pro（12 核、64GB）
- 專案：ricardodantas/hazelnut（https://github.com/ricardodantas/hazelnut），GPL-3.0 授權
- 測試版本：0.3.0
- 實測影片：https://www.youtube.com/shorts/Wo-IK7qapvM

## 重點摘要

- Hazelnut 依規則自動搬檔：寫好設定檔後，新檔案進下載夾就被搬到對的資料夾。
- Mac 與 Linux 可開常駐全自動；Windows 依官方說明沒有常駐，只能手動執行。
- 流程六步：安裝、寫設定檔、hazelnut check、預覽（預設不搬）、--apply 真的搬、hazelnutd start 常駐。
- 實測：同名檔案不覆蓋、留在下載夾；沒寫規則的類型原地不動；常駐模式新檔約三秒歸位。
- **結論：** 下載夾天天要手動拖檔的辦公室值得花一次時間設定；它不讀檔案內容，Windows 只能手動執行。
- **適合：** 下載夾常堆滿辦公檔案、有懂電腦的同事能協助首次設定的人
- **不適合：** 想讓它看懂檔案內容分類、或完全不想碰設定檔的人

| 實測項目 | 結果 |
|---|---|
| 項目 | 實測結果 |
| 版本 | Hazelnut 0.3.0 |
| 實測系統 | Linux aarch64 |
| 原始碼安裝 | 約 52 秒 |
| 設定檢查 | 1 個監看資料夾、4 條規則通過 |
| 預覽 | 10 個檔案都沒動 |
| --apply | 下載夾剩 0 個 |
| 常駐 | 新檔約 3 秒歸位 |
| 同名檔 | 不覆蓋，留在下載夾 |
| 沒寫規則的類型 | 原地不動 |

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

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

## 先看你的電腦能做到哪裡

| 系統 | 安裝方式 | 能不能常駐全自動 |
|---|---|---|
| macOS | Homebrew | 可以（依官方說明，本篇未在 Mac 實測） |
| Linux | Homebrew、cargo、Arch 的 pacman | 可以（本篇實測） |
| Windows | cargo，或下載 GitHub Releases 的執行檔 | 不行：官方說明常駐程式 `hazelnutd` 只有 macOS 與 Linux，Windows 只能手動執行 |

使用前要知道的條件：

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

## 步驟一：安裝

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

```bash
brew install ricardodantas/tap/hazelnut
```

Linux：

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

Windows：

```bash
cargo install hazelnut
```

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

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

裝完確認版本：

```bash
hazelnut --version   # 本篇：hazelnut 0.3.0
```

## 步驟二：寫設定檔

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

```bash
mkdir -p ~/.config/hazelnut
```

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

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

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

```toml
# 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`。

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

```bash
hazelnut check
```

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

![hazelnut check 檢查通過：1 個監看資料夾、4 條規則](https://blog.valenvan.uk/img/ricardodantas-hazelnut-article_1.png)

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

```bash
hazelnut run -d ~/Downloads
```

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

![預覽列出 10 個檔案各自的目的地，下載夾仍是 10 個](https://blog.valenvan.uk/img/ricardodantas-hazelnut-article_2.png)

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

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

```bash
hazelnut run -d ~/Downloads --apply
```

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

![加上 --apply 後下載夾剩 0 個，檔案分別進了文件、簡報、照片、安裝檔](https://blog.valenvan.uk/img/ricardodantas-hazelnut-article_3.png)

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

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

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

![常駐模式：新檔案三秒內離開下載夾，各自歸位](https://blog.valenvan.uk/img/ricardodantas-hazelnut-article_4.png)

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）