安裝前：了解客戶端、核心與設定檔

Clash Nyanpasu 是桌面圖形介面客戶端。視窗能開啟，只代表介面程序已啟動；要讓網路請求經過代理，還需要執行中的代理核心、有效設定檔，以及將流量導入核心的入口。初次設定建議依序進行「安裝 → 匯入設定檔 → 啟動核心 → 手動測試代理 → 設定系統代理」，暫時先關閉 TUN。

  • 客戶端：負責管理設定檔、提供設定介面、顯示記錄檔及整合系統功能。
  • 核心：讀取設定並處理連線。mihomo 常稱為 Clash Meta 核心，實際可選項目依客戶端發行版本而異。
  • Profile：本機設定檔或遠端訂閱記錄。設定檔通常包含節點、策略群組、DNS 與路由規則。
  • 代理入口：例如本機 HTTP/SOCKS 監聽連接埠或 TUN 虛擬網卡。入口不同，接管的流量範圍也不同。

Windows、macOS 與 Linux 安裝步驟

Windows：確認系統類型與安裝權限

  1. 開啟「設定」→「系統」→「系統資訊」，查看「系統類型」。x64 與 ARM64 請選擇相符的版本；不要只根據 Windows 11 的名稱判斷處理器架構。
  2. 前往下載頁面，選擇目前版本提供的安裝檔。依照一般流程安裝並啟動，記下任何缺少相依元件或系統安全性提示的完整內容。
  3. 初次啟動時，請以一般使用者權限匯入設定檔並測試本機連接埠。需要服務模式或 TUN 時，再依客戶端提示安裝服務或授予權限。
  4. 若出現 WebView2 相關錯誤，請依該版本的安裝說明檢查執行階段元件。離線裝置需準備符合處理器架構的執行階段安裝檔；不要把介面相依元件錯誤誤判為訂閱錯誤。

可在 Windows「設定」→「網路和網際網路」→「Proxy」中確認系統代理設定。測試時不要同時執行兩個會修改系統代理的客戶端，否則後寫入設定的程式可能覆蓋另一個程式設定的位址與連接埠。

macOS：確認晶片型號，再處理安全性提示

  1. 從 Apple 選單 →「關於這台 Mac」查看「晶片」或「處理器」。Apple 晶片裝置請選擇相符的 ARM64 版本，Intel 裝置則選擇 x64 版本；通用版本請以下載頁面的標示為準。
  2. 若下載的是磁碟映像檔，開啟後請將應用程式拖移至「應用程式」資料夾，再從該資料夾啟動，避免長期直接從掛載的映像檔執行。
  3. 若系統提示無法開啟，請先確認來源與系統相容性，再依「系統設定」→「隱私權與安全性」中實際顯示的選項處理。不要為了執行單一應用程式而關閉整個系統的安全機制。
  4. 只有在啟用相關功能時，才需要處理權限要求。使用本機代理監聽與系統代理，不代表必須核准所有網路延伸功能或鑰匙圈存取要求。

較新版本的 macOS 可前往「系統設定」→「網路」→目前使用的網路服務→「詳細資訊」→「代理」查看代理狀態。不同系統版本的選單名稱可能略有差異。若授權對話框反覆出現，請先記下要求存取的項目及內容，再判斷是否涉及安裝服務、系統網路設定或存取憑證。

Linux：區分套件格式、架構與桌面環境

先執行 uname -m 查看架構：常見的 x86_64 對應 x64，aarch64 對應 ARM64。接著依據發行版和目前版本提供的檔案選擇安裝方式。使用套件管理員安裝與執行 AppImage 是不同途徑，請勿混用命令。

  • 發行版套件：透過系統套件管理員安裝，並檢查相依套件解析結果。若缺少圖形執行階段程式庫，請依錯誤訊息補齊相依套件。
  • AppImage：先授予檔案執行權限；若記錄檔指出 FUSE 問題，請依發行版與該版本的說明處理。不要長期以 root 身分執行圖形介面來規避問題。
  • 桌面環境的系統代理：GNOME、KDE 與終端機程式讀取代理設定的方式各不相同。即使客戶端顯示系統代理已啟用，仍需確認目標應用程式是否採用該設定。

Linux 桌面環境啟動後沒有視窗時，請從終端機執行實際安裝的執行檔並保留輸出內容。缺少共享程式庫、顯示工作階段無法使用與核心設定錯誤屬於不同層級；排查時應先處理最早出現的明確錯誤。

匯入設定檔：先準備可運作的 Profile

在客戶端的設定檔管理頁面新增本機 YAML 或遠端訂閱，等待匯入完成，再將該設定檔設為目前使用的項目。不同版本的按鈕可能標示為「設定檔」、「Profiles」或類似名稱；操作目標都是建立設定檔記錄並啟用，而不只是把連結存進輸入框。

  1. 確認訂閱服務商支援 Clash YAML，或目前核心可辨識的設定格式。瀏覽器能開啟連結，不代表回傳內容就適合直接匯入。
  2. 確認下載內容是否為設定檔文字。登入頁面、訂閱過期提示、HTML 錯誤頁面，以及只有節點清單的內容，都可能造成解析失敗或缺少策略群組。
  3. 啟用設定檔後查看記錄，確認沒有 YAML 解析錯誤、未知欄位造成的啟動失敗，或不存在的規則目標。
  4. 前往代理或策略群組頁面，確認有可供選取的節點。若群組中只有 DIRECT，應繼續檢查設定檔內容，而不是反覆切換系統代理。

訂閱 URL 可能包含存取權杖。分享截圖、提問或複製記錄檔前，請遮蔽 URL 查詢參數、節點密碼與控制介面金鑰。遠端訂閱更新時會覆寫原始內容；本機修改能否保留，取決於客戶端的設定處理機制。若要長期自訂，建議使用該版本支援的覆寫方式。

核心與連接埠：先確認實際生效值

初次安裝時，建議先使用客戶端隨版本提供的核心。若需使用 mihomo 專屬欄位，請先確認目前執行的核心及版本是否支援。切換核心後，必須重新載入設定檔並查看新程序的啟動記錄；介面上選取某個名稱，並不能證明新核心已成功執行。

欄位或設定用途初次檢查
mixed-port在同一個連接埠提供 HTTP 與 SOCKS 代理入口。記下實際監聽的連接埠，測試時使用相同的客戶端位址。
allow-lan控制是否允許區域網路裝置連線使用代理。僅供本機使用時請保持關閉，並確認綁定位址。
mode選擇規則、全域或直連等運作模式。日常使用可先從規則模式開始，並確認規則目標有效。
external-controller提供客戶端與核心之間的控制介面。控制介面的連接埠不可填入瀏覽器代理連接埠。

以下 YAML 片段用於說明欄位之間的關係，並非包含節點與規則的完整訂閱。請勿用它覆蓋目前的整份設定檔。客戶端的覆寫設定可能會改變最終值，因此應以實際執行設定與記錄為準。

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

控制介面與流量入口必須分開理解。例如，某份設定將控制介面設為 127.0.0.1:9090，這個位址是用來管理核心，不是轉送網頁請求。若無必要的存取控制，不應讓控制介面監聽所有網路介面。

連線驗證：手動代理、系統代理與 TUN

步驟一：透過明確指定代理測試連接埠

先選擇可用的策略群組與節點，再明確指定本機代理，送出單次測試請求。以下命令會連線至標準 HTTPS 範例網域；成功取得回應只代表這次請求可完成，不表示所有網站、通訊協定和應用程式都已接管。Windows 請使用 curl.exe，避免部分 PowerShell 環境中的同名別名影響參數解析。

# Windows PowerShell
curl.exe -I --proxy http://127.0.0.1:7890 --connect-timeout 10 https://example.com

# macOS / Linux
curl -I --proxy http://127.0.0.1:7890 --connect-timeout 10 https://example.com

若出現無法連線至 127.0.0.1 的訊息，請先檢查連接埠與執行中的程序。若代理連線已建立但之後逾時，請配合記錄檔檢查節點連線、TLS、DNS 與規則結果。收到 HTTP 錯誤狀態不代表本機代理未執行，應區分「連線狀態」與「目標網站回傳的內容」。

步驟二：啟用系統代理並觀察連線

明確指定代理的測試通過後，再啟用客戶端的系統代理設定，重新啟動測試應用程式或建立新連線，並在客戶端的連線清單中確認目標網域、命中的規則與最終策略。系統代理只會影響遵循系統設定的應用程式；既有連線、部分終端機工具，以及自行管理網路連線的程式可能不受切換影響。

終端機環境中的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 與 NO_PROXY 也可能改變請求路徑。排查單一程式時，請先檢查程式本身的代理設定與環境變數，不要直接認定系統代理失效。

步驟三：有需要時再啟用 TUN

TUN 會透過虛擬網路介面與路由接管流量，適用於系統代理無法涵蓋的部分情境。通常需要額外權限或服務支援，也涉及 DNS、路由與介面選擇。若一般瀏覽器測試尚未通過，不建議同時啟用 TUN，以免混淆節點問題與路由問題。

  • 先關閉其他 VPN 或同類型的 TUN 客戶端，避免重複接管路由與 DNS。
  • 依目前版本的提示安裝服務或授予權限，再確認記錄中已成功建立虛擬介面。
  • 分別測試一般網頁、區域網路位址及需要接管的應用程式；不要只看 TUN 開關是否已啟用。
  • 若發生全面斷網，請先關閉 TUN，確認網路恢復後再檢查路由與 DNS 設定，不要持續疊加修改。

啟動失敗與連接埠衝突的排查順序

視窗無法開啟：先檢查介面層

先確認安裝檔架構、系統支援範圍與安裝路徑。Windows 請查看相依元件提示，macOS 請查看系統安全性提示，Linux 請檢查終端機輸出。此時尚未進入核心監聽階段，修改訂閱規則通常無法解決介面啟動失敗。若升級前後行為不同，請保留原設定檔備份、客戶端版本及錯誤發生時間。

視窗正常、核心啟動失敗：查看第一筆錯誤

若記錄中出現 address already in use 或 bind 相關錯誤，請確認發生衝突的是代理連接埠、DNS 監聽連接埠，還是控制介面。以下命令只會查詢範例代理連接埠 7890，請替換為錯誤訊息中的實際數值。

# Windows PowerShell：查看監聽程序 PID
Get-NetTCPConnection -LocalPort 7890 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

# macOS：查看 TCP 監聽程序
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux：查看監聽資訊；查看程序詳情可能需要額外權限
ss -ltnp 'sport = :7890'
  1. 依 PID 確認所屬程序，優先正常關閉重複啟動的舊客戶端；不要終止來源不明的系統程序。
  2. 若必須同時執行兩個程式，請將其中一個代理監聽連接埠改為其他未占用的數值，例如 7891。
  3. 修改連接埠後，請同步更新系統代理、瀏覽器與終端機的明確代理位址，並重新載入設定檔。
  4. 再次查詢監聽狀態，然後重新執行連線測試。不要只改介面上顯示的數值，卻忽略實際生效的設定。

若記錄指出 YAML 行號、縮排或策略群組名稱有誤，請先修正設定檔。YAML 階層使用空格縮排，同一層級的欄位須對齊；規則引用的策略名稱必須與現有群組名稱相符。欄位說明請參閱YAML 設定參考。

可以啟動但無法連線：逐段檢查連線路徑

依序檢查「應用程式是否使用代理 → 本機連接埠是否在監聽 → 規則命中哪個策略 → 節點是否可連線 → DNS 是否正常」。單一延遲測試數值無法代表整條連線路徑；規則模式下，某個請求也可能命中 DIRECT，完全沒有經過目前手動選取的節點。

完成初始設定後的注意事項

  • 記錄版本與參數：客戶端版本、核心版本、目前的 Profile 名稱、代理連接埠，以及是否啟用 TUN。
  • 確認結束執行後的狀態：正常結束客戶端後，確認系統代理已還原；若非預期結束後仍殘留代理位址，請在系統網路設定中手動關閉，再檢查網路。
  • 最後再啟用開機啟動：先完成一次結束執行、重新啟動與連線測試，再啟用開機啟動，避免登入後反覆遇到相同錯誤。
  • 妥善保管備份：匯出的設定檔可能包含訂閱權杖與節點憑證。請只存放在可信任的儲存位置，勿將完整設定檔張貼至公開討論區。

初次安裝的完成標準，不是所有開關都已開啟，而是目前的設定檔能載入、代理入口能正常監聽，且能確認目標應用程式的請求路徑。請保留一份已驗證的基本設定，之後再逐項加入自訂規則、覆寫設定或 TUN，日後回復與排查都會更容易。