FreeGuard CLI 疑難排解

使用 FreeGuard CLI 遇到問題了嗎？本指南涵蓋最常見的問題及其解決方案。遇到任何問題時，請先嘗試執行 freeguard doctor — 它能自動偵測大多數設定和環境問題。

安裝問題

安裝時權限被拒絕

症狀： 安裝腳本顯示 Permission denied 或 EACCES 錯誤。

解決方案： 在 macOS/Linux 上，安裝程式需要對 /usr/local/bin 的寫入權限。請以提升的權限執行：

curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sudo sh

在 Windows 上，請確保在執行安裝指令前以系統管理員身分開啟 PowerShell。

安裝後找不到指令

症狀： 執行 freeguard 時回傳 command not found 或 not recognized。

Doctor 輸出：

✗ CLI binary:     Not in PATH

解決方案： 二進位檔案可能不在您 shell 的 PATH 中。手動新增：

# macOS/Linux — add to your shell profile (~/.bashrc, ~/.zshrc)
export PATH="$HOME/.freeguard/bin:$PATH"

# Then reload your shell
source ~/.zshrc  # or ~/.bashrc

在 Windows 上，將 %USERPROFILE%\.freeguard\bin 加入系統 PATH 環境變數中，並重新啟動終端機。

curl 失敗或下載逾時

症狀： 安裝腳本無法下載二進位檔案。

解決方案： 如果您在企業防火牆後方或受限網路中，請從 GitHub Releases 頁面手動下載二進位檔案，並放入 ~/.freeguard/bin/ 目錄。然後使其可執行：

chmod +x ~/.freeguard/bin/freeguard

登入問題

未收到驗證碼

症狀： 執行 freeguard login --email [email protected] --send-code 後沒有收到郵件。

解決方案：

檢查垃圾郵件資料夾 — 驗證郵件有時會被過濾。
等待 2 分鐘後再重新請求。傳送驗證碼有頻率限制。
確認電子郵件地址是否正確：

freeguard login --email [email protected] --send-code

如果問題持續，嘗試使用其他電子郵件服務商。

Token 過期

症狀： 指令顯示 Authentication expired 或 Token invalid 錯誤。

Doctor 輸出：

✗ Credentials:     Token expired (last refresh: 2026-03-01)

解決方案： 重新登入以重新整理憑證：

freeguard logout
freeguard login --email [email protected] --send-code

電子郵件錯誤 — 未找到訂閱

症狀： 登入成功，但 freeguard connect 顯示 No active subscription。

Doctor 輸出：

✓ Credentials:     Logged in (email: u***@example.com)
✗ Subscription:    No active subscription found

解決方案： 請確保使用購買訂閱時的同一電子郵件登入。如果使用了不同的電子郵件：

freeguard logout
freeguard login --email [email protected] --send-code

連線問題

連線逾時

症狀： freeguard connect 卡住或回傳 Connection timed out。

Doctor 輸出：

✗ Network:         Internet not reachable

解決方案：

檢查基本網路連線（先中斷 VPN）：

freeguard disconnect
ping 8.8.8.8

嘗試不同的節點或國家：

freeguard connect --country SG

嘗試可能在您網路上效果更好的其他協定：

freeguard connect --protocol hysteria2

連接埠 7890 已被佔用

症狀： freeguard connect 顯示 Port 7890 is already in use。

Doctor 輸出：

✗ Port 7890:       In use by another process (PID: 12345)

解決方案： 其他代理應用程式正在使用預設連接埠。停止另一個應用程式，或更改 FreeGuard 代理連接埠：

freeguard config set proxy.port 8080
freeguard connect

偵測到 DNS 洩漏

症狀： DNS 查詢繞過了 VPN 通道。

解決方案： 切換到安全 DNS 設定：

freeguard config set dns.provider secure
freeguard disconnect
freeguard connect

您可以驗證 DNS 是否透過 VPN 路由：

freeguard doctor

在輸出中尋找 DNS 檢查項，確認其正常運作。

權限問題

TUN 模式需要 sudo

症狀： freeguard connect --tun 顯示 Permission denied: TUN device。

Doctor 輸出：

✗ TUN permission:  Not available (run with sudo for TUN mode)

解決方案： TUN 模式會建立虛擬網路介面，需要提升的權限：

# macOS/Linux
sudo freeguard connect --tun

# Windows — run PowerShell as Administrator
freeguard connect --tun

如果不需要系統級 VPN 覆蓋，請使用預設的系統代理模式（無需 sudo）：

freeguard connect

1024 以下連接埠需要提升權限

症狀： 設定 1024 以下的代理連接埠時顯示 Permission denied。

解決方案： 大多數作業系統限制 1024 以下的連接埠。請使用 1024 以上的連接埠：

freeguard config set proxy.port 7890

或者如果確實需要低連接埠，以提升的權限執行：

sudo freeguard connect

仍然無法解決？

如果 freeguard doctor 和以上方案都無法解決您的問題，讓 AI 自動診斷。

造訪 FreeGuard CLI Agent 頁面，描述您的問題。Agent 可以讀取您的 freeguard doctor --json 輸出，逐步引導您完成修復。

您也可以執行互動式疑難排解精靈：

freeguard doctor --json | pbcopy
# Then paste the output into the CLI Agent chat

常見問題

為什麼 FreeGuard CLI 顯示 “connection refused”？

這通常表示 VPN 伺服器暫時不可用。嘗試 freeguard connect --server auto 自動選擇最佳可用伺服器，或檢查防火牆設定。

如何檢查 VPN 連線是否正常？

執行 freeguard status 查看連線狀態、目前伺服器和協定。也可以執行 curl ifconfig.me 驗證 IP 位址是否已變更。

系統更新後 FreeGuard CLI 無法啟動怎麼辦？

執行 freeguard update 取得最新版本。如果失敗，使用安裝腳本重新安裝：curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh。

如何回報錯誤或取得協助？

執行 freeguard debug 收集診斷資訊，然後透過網站或電子郵件聯繫客服。附上除錯輸出以加快問題解決。

最後更新：2026 年 3 月