Linux 安裝 mihomo 核心：桌面客戶端與 systemd 命令列部署方式

先選擇執行方式：桌面管理或獨立服務

日常在 Linux 桌面切換節點、匯入訂閱，建議使用圖形客戶端。若要在無桌面的主機上持續執行，或希望登入前就啟動代理入口，則選擇獨立 mihomo 核心搭配 systemd。兩種方式共用規則設定概念，但設定目錄、更新方式與權限來源各不相同；客戶端的開機啟動與系統服務並非同一項設定。

mihomo 是網路處理核心，也常稱為 Clash Meta 核心；圖形客戶端則負責設定管理、操作介面與系統整合。安裝核心不會自動新增系統匣圖示、修改 GNOME 代理設定，也不會讓所有命令列程式自動透過代理連線。本文會先建立僅監聽本機 127.0.0.1:7890 的代理入口，再確認應用程式是否確實連上該連接埠。

在 Ubuntu、Debian、Arch 安裝桌面客戶端

確認系統架構與安裝套件類型

先執行以下兩個命令。x86_64 通常對應 x64 或 amd64 套件，aarch64 通常對應 arm64 套件。Ubuntu、Debian 優先選擇適用於該發行版的 DEB；Arch 不使用 DEB 或 RPM 直接安裝。客戶端能否執行，也取決於系統程式庫與桌面環境，不只看處理器架構。

uname -m
cat /etc/os-release

前往客戶端下載頁確認 Linux 套件與維護狀態，並比較 Clash Verge Rev、FlClash 等客戶端對各發行版的實際支援情況。本文不固定客戶端版本；安裝後請在「關於」頁記下客戶端版本，並從日誌或核心資訊頁記下核心版本，方便日後重現問題。

• Ubuntu / Debian：下載適用於本機的 DEB 後，可將本機檔案重新命名為 client.deb，再執行 sudo apt install ./client.deb。此名稱僅供本機重新命名使用，並非發行套件名稱。
• Arch：選擇維護者提供且適用於 Arch 的安裝方式。使用 AUR 前，請先閱讀 PKGBUILD 與下載來源；AUR 套件由社群維護，並非官方套件庫套件。不要為了配合安裝套件而混用其他發行版的系統程式庫。
• 可攜式套件：若發行方提供 AppImage，請先授予執行權限再啟動。遇到 FUSE 或圖形程式庫錯誤時，依照該套件的說明安裝相依套件；不要以 root 身分啟動圖形介面來規避錯誤。

匯入設定後，先確認本機連接埠

1. 在客戶端的「設定」頁匯入相容於 mihomo 的 YAML 或訂閱，並確認目前啟用的項目。訂閱網址通常包含存取憑證，請勿貼到公開日誌中。
2. 在「設定」中確認實際使用的 HTTP、SOCKS 或混合連接埠。本文範例一律使用混合連接埠 7890；客戶端預設值可能不同，執行命令時請依實際設定調整。
3. 先關閉 TUN，只啟用要測試的代理入口。查看日誌，確認設定載入成功後，再使用下文的明確指定代理命令進行測試。
4. 若要讓桌面應用程式使用代理，請啟用客戶端的「系統代理」。也可在 GNOME 依序前往「設定」→「網路」→「網路代理」→「手動」，確認位址與連接埠；不同桌面環境的設定路徑可能不同。

桌面客戶端的「開機啟動」通常依賴使用者工作階段。若需要在無人登入時也能執行，請使用下方的 systemd 方式；不要同時保留桌面核心的自動啟動。關閉客戶端前，也請確認它已取消系統代理設定，避免系統繼續連向已關閉的連接埠。

獨立 mihomo：準備目錄與最基本設定

安裝執行檔並建立專用使用者

從核心發行管道取得符合系統架構的 Linux 執行檔，依套件格式解壓縮，並將解壓後的執行檔命名為 mihomo。以下命令會安裝目前目錄中的這個檔案，不預設任何遠端安裝套件名稱。請先確認能輸出版本資訊，再繼續設定服務。

chmod +x ./mihomo
./mihomo -v
sudo install -m 0755 ./mihomo /usr/local/bin/mihomo

sudo useradd --system --user-group --no-create-home \
  --home-dir /var/lib/mihomo --shell /bin/false mihomo
sudo install -d -o root -g mihomo -m 0750 /etc/mihomo
sudo install -d -o mihomo -g mihomo -m 0750 /var/lib/mihomo

若專用使用者已存在，請勿重複建立；先執行 id mihomo 確認使用者與群組。執行檔由 root 管理，執行資料則由服務使用者持有；設定目錄僅允許 root 與 mihomo 群組存取。訂閱內容可能包含節點密碼，因此不應將設定放在所有人都能讀取的目錄。

先用直連設定確認服務正常，不要將它當成節點設定

執行 sudoedit /etc/mihomo/config.yaml，寫入以下設定。這份設定只會提供本機混合代理入口，所有請求仍採直連；目的是區分安裝、權限與監聽問題。沒有代理節點時，服務成功執行不代表已取得遠端代理出口。

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: false

tun:
  enable: false

rules:
  - MATCH,DIRECT

sudo chown root:mihomo /etc/mihomo/config.yaml
sudo chmod 0640 /etc/mihomo/config.yaml
sudo -u mihomo /usr/local/bin/mihomo -t \
  -d /var/lib/mihomo -f /etc/mihomo/config.yaml

-f 用來指定主要設定檔，-d 用來指定資料目錄，-t 則用來測試設定。測試通過只代表設定可載入，不保證能連線至遠端節點。改用實際訂閱設定後，還要確認策略群組名稱、規則引用與 provider 路徑；相對於執行資料的路徑應統一放在可寫入的資料目錄，不要指向桌面使用者的私人目錄。

使用 systemd 管理服務：啟動、日誌與開機自動啟動

執行 sudoedit /etc/systemd/system/mihomo.service，寫入以下完整服務定義。此設定適用於一般本機代理，不啟用 TUN，也不繫結 53 等低連接埠。工作目錄與可寫入目錄一致，設定檔則維持唯讀。

[Unit]
Description=mihomo local proxy service
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

network-online.target 是否生效，取決於系統有沒有啟用相應的網路等待服務；不能因此認定遠端訂閱一定可連線。首次啟動若需要下載規則或地理資料，請查看日誌確認下載狀態；若環境在啟動時無法連上網路，請事先準備設定所需資料。

sudo systemd-analyze verify /etc/systemd/system/mihomo.service
sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -b -n 80 --no-pager
ss -lntp 'sport = :7890'

• enable --now 會同時設定開機啟動並立即啟動服務；只執行 enable 不會立刻啟動程序。
• 正常狀態應顯示為 active (running)，連接埠檢查應能看到本機 7890 的監聽紀錄。一般使用者執行 ss 時，可能看不到其他使用者的程序名稱。
• 更新設定後，先重新執行 -t 測試，再執行 sudo systemctl restart mihomo。只修改 YAML 不需要執行 daemon-reload；修改服務檔案才需要。
• 若要暫時停止服務，執行 sudo systemctl stop mihomo；若要同時取消開機啟動，執行 sudo systemctl disable --now mihomo。

本文未設定 ExecReload，因此不要用 systemctl reload 取代重新啟動。若要透過外部控制器熱載入設定，必須另外規劃驗證方式與監聽範圍；基本服務不必為了管理介面而開放控制連接埠。

驗證代理連線：分別檢查連接埠、請求與規則

先明確指定代理，再檢查環境變數

以下兩個命令分別用來測試 HTTP 代理與 SOCKS5 代理。--noproxy "" 會清空這次請求的略過清單，避免既有的 NO_PROXY 設定讓測試直接繞過代理。SOCKS 範例使用 socks5h，讓目標網域交由代理端解析。

curl --noproxy "" -I --connect-timeout 10 --max-time 20 \
  -x http://127.0.0.1:7890 https://example.org/

curl --noproxy "" -I --connect-timeout 10 --max-time 20 \
  --proxy socks5h://127.0.0.1:7890 https://example.org/

收到 HTTP 回應代表這次請求已完成，但仍須搭配核心日誌確認命中的規則。最基本的設定會顯示為直連；啟用實際節點後，才需要確認是否命中預期的策略群組，以及該群組選用了哪個節點。延遲測試成功也不能取代實際 HTTPS 請求。

若明確指定代理後測試成功，但一般終端機命令仍未透過代理連線，可在目前的 shell 暫時設定環境變數。不同程式支援的變數名稱不盡相同；以下寫法適用於常見命令列工具，不會接管所有程式。

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5h://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

curl -I --connect-timeout 10 --max-time 20 https://example.org/

unset http_proxy https_proxy all_proxy no_proxy

https_proxy 的值使用 http:// 並不矛盾：這代表透過 HTTP 代理的 CONNECT 通道連線至 HTTPS 目標。若將設定寫入 shell 設定檔，服務關閉後也要記得移除；瀏覽器、APT 與由 systemd 啟動的其他服務不一定會繼承這些變數，請分別依應用程式設定。

依錯誤類型排查常見問題

• Connection refused：先確認 7890 是否正在監聽，並核對連接埠與服務狀態；此時不必先更換節點。
• address already in use：檢查桌面客戶端或舊核心程序是否占用連接埠，並只保留一個代理入口。
• permission denied：確認檔案與上層目錄的權限，並以服務使用者執行設定測試；不要用 chmod 777 掩蓋問題。
• 規則或資料下載失敗：檢查 provider 位址、資料目錄是否可寫入，以及啟動時的網路狀態。先保留完整錯誤內容，再判斷是否為 DNS 問題。
• 服務不斷重新啟動：使用 journalctl 找出最早出現的設定或資源錯誤。修正後若觸發啟動頻率限制，可執行 sudo systemctl reset-failed mihomo 再啟動服務。

TUN 與更新維護：維持權限界線

啟用 TUN 不只是把 enable 改成 true

TUN 需要存取 /dev/net/tun，通常也需要建立介面、調整路由，以及接管 DNS 所需的網路管理權限。檢查 ls -l /dev/net/tun 只能確認裝置節點存在，無法證明目前的服務已取得所需授權。本文的一般使用者服務刻意不設定這些權限，因此不能直接用於 TUN。

若需要使用 TUN，請先選擇客戶端提供的授權服務，或依目前 mihomo 版本的說明重新規劃 systemd 權限與能力限制。不要只把服務使用者改成 root，就照搬所有設定。請先停用另一套網路接管功能，確認 DNS 監聽連接埠、路由範圍及是否接管區域網路流量，再測試內網存取與停用後的路由復原情況。

更新前記錄版本，更新後重新驗證

1. 記下 /usr/local/bin/mihomo -v 的輸出，並備份目前的執行檔與設定。備份設定也應維持受限權限。
2. 下載符合系統架構的新核心，先執行新檔案的 -v 與 -t；測試時仍使用服務使用者與相同的資料目錄。
3. 停止服務後，使用 install -m 0755 替換執行檔，再啟動服務。請勿嘗試直接覆寫正在執行的檔案。
4. 重新檢查日誌、7890 監聽狀態與 HTTPS 請求。若新版本出現相容性問題，請停止服務，還原舊執行檔與設定後重新啟動。

最後分別確認三件事：systemd 能穩定管理程序、本機應用程式能連上代理連接埠，以及實際請求能命中正確規則與節點。三項都確認無誤，才算完成部署。更多基本設定請參閱使用指南；若瀏覽器與終端機的結果不一致，可依照故障排除逐項確認應用程式使用的代理來源。