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 月