Skip to content

FAQ

Jump to bottom
Juwan-Hwang edited this page Apr 16, 2026 · 6 revisions

常见问题解答 (FAQ)

本文档汇总了 Zephyr 使用过程中的常见问题与解答。如果本文档未能解决你的问题，请在 GitHub Issues 中提交。

目录

故障排除决策树

遇到问题时，请参照以下决策树快速定位解决方案：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A[遇到问题] --> B{问题类型?}

    B -->|安装/启动失败| C[安装问题]
    B -->|功能异常| D[使用问题]
    B -->|代理/规则不生效| E[配置问题]
    B -->|隐私/权限/漏洞| F[安全问题]

    C --> C1{安装阶段?}
    C1 -->|下载失败| C2[检查网络连接<br/>尝试手动下载]
    C1 -->|安装报错| C3[检查系统兼容性<br/>查看安装日志]
    C1 -->|启动崩溃| C4[查看崩溃日志<br/>检查依赖完整性<br/>以管理员身份运行]
    C1 -->|端口占用| C5[关闭冲突程序<br/>修改默认端口]

    D --> D1{具体症状?}
    D1 -->|无法连接| D2[检查节点状态<br/>测试订阅可用性]
    D1 -->|速度慢| D3[切换节点/协议<br/>检查本地网络]
    D1 -->|频繁断连| D4[启用 URL 测试组<br/>检查系统休眠设置]
    D1 -->|UI 无响应| D5[重启应用<br/>清理缓存]

    E --> E1{配置类型?}
    E1 -->|订阅问题| E2[检查订阅链接<br/>手动更新订阅]
    E1 -->|规则不匹配| E3[检查规则语法<br/>查看日志匹配记录]
    E1 -->|DNS 问题| E4[检查 DNS 设置<br/>尝试 DoH/DoT]
    E1 -->|TUN 模式异常| E5[检查权限<br/>重启 TUN 服务]

    F --> F1{安全类型?}
    F1 -->|证书错误| F2[更新根证书<br/>检查系统时间]
    F1 -->|权限问题| F3[检查文件权限<br/>以管理员运行]
    F1 -->|日志泄露| F4[配置日志级别<br/>定期清理日志]
    F1 -->|漏洞担忧| F5[查看安全公告<br/>更新至最新版本]
Loading

安装与启动

Q1: Zephyr 支持哪些操作系统？

A: Zephyr 支持以下操作系统：

操作系统 最低版本 架构
Windows Windows 10 1809+ x64
macOS macOS 10.13 High Sierra x64, ARM64 (Apple Silicon)
Linux Ubuntu 20.04+ / Fedora 36+ x64

不支持 Windows 7/8/8.1、macOS 11 及以下、32 位系统。

Q2: Full 版和 Lite 版有什么区别？

A:

特性 Full 版 Lite 版
Mihomo 内核 内置 不含
安装包大小 ~30MB ~8MB
首次使用 开箱即用 需自行放置内核
适用场景 新用户、普通用户 高级用户、自定义内核

如果你是首次使用，推荐下载 Full 版。如果你需要使用自定义编译的 Mihomo 内核，可以选择 Lite 版。

Q3: 安装时被杀毒软件拦截怎么办？

A: 这是误报。Zephyr 是开源项目，代码完全透明。你可以：

  1. 将 Zephyr 安装目录添加到杀毒软件白名单
  2. 临时关闭杀毒软件完成安装后重新开启
  3. 从 GitHub Releases 页面下载后验证 SHA256 校验和，确认文件完整性

Q4: 启动 Zephyr 时闪退怎么办？

A: 请按以下步骤排查：

  1. 打开终端/命令提示符，从命令行启动 Zephyr，查看错误输出
  2. 检查日志文件（位于应用数据目录下的 logs/ 文件夹）
  3. 确认系统满足最低要求
  4. Windows 用户尝试以管理员身份运行
  5. Linux 用户确认是否安装了所需的系统依赖（libwebkit2gtk-4.1 等）

以下流程图展示了启动失败的完整诊断路径：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["启动失败"] --> B["检查错误日志"]
    B --> C{"有错误信息?"}

    C -->|"是"| D["检查Mihomo内核是否存在"]
    D --> E{"内核存在?"}
    E -->|"是"| F["检查配置文件语法<br/>(mihomo -t)"]
    F --> G{"语法通过?"}
    G -->|"是"| H["检查端口占用"]
    G -->|"否"| I["修复配置语法"]
    E -->|"否"| J["重新下载内核"]

    C -->|"否"| K["检查系统依赖<br/>(WebView2 / libwebkit2gtk)"]
    K --> L{"Windows?"}
    L -->|"是"| M["检查VC++运行时"]
    K --> N{"Linux?"}
    N -->|"是"| O["安装libwebkit2gtk-4.1-0"]

    style A fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style J fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style I fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style M fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style O fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style H fill:#c8e6c9,stroke:#10B981,color:#10B981
    style B fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style D fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style F fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style K fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style C fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style E fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style G fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style L fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style N fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
Loading

Q5: macOS 提示"已损坏，无法打开"怎么办？

A: 这是 macOS Gatekeeper 对未签名应用的限制。解决方法：

# 方法 1：移除隔离属性
xattr -cr /Applications/Zephyr.app

# 方法 2：允许任何来源（系统设置 → 隐私与安全性）
sudo spctl --master-disable

使用问题

Q6: 添加订阅后没有节点显示？

A: 可能的原因和解决方案：

  1. 订阅链接无效：在浏览器中打开订阅链接，确认返回的是 Base64 编码的节点列表
  2. 网络问题：确保本机可以访问订阅服务器（可能需要先关闭代理）
  3. 编码问题：确认订阅链接返回的是标准格式（Clash/Mihomo YAML 或 Base64）
  4. 更新间隔：点击手动更新按钮强制刷新订阅

Q7: 代理开启后无法上网？

A: 按以下顺序排查：

  1. 确认已选择一个可用节点
  2. 测试节点延迟，排除不可用节点
  3. 检查系统代理设置是否正确（Zephyr 默认监听 127.0.0.1:7890）
  4. 尝试切换代理模式（规则模式 / 全局模式 / 直连模式）
  5. 检查防火墙是否阻止了 Zephyr 的网络连接

以下流程图展示了代理连接异常的完整诊断路径：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["无法上网"] --> B["检查节点是否选中"]
    B --> C{"已选中?"}

    C -->|"是"| D["测试节点延迟"]
    D --> E{"延迟正常?"}
    E -->|"是"| F["检查系统代理设置<br/>(127.0.0.1:7890)"]
    F --> G{"设置正确?"}
    G -->|"是"| H["检查防火墙规则"]
    H --> I["尝试切换模式<br/>(Rule/Global/Direct)"]
    G -->|"否"| J["修正系统代理设置"]

    E -->|"否"| K["延迟超时"]
    K --> L["检查订阅是否过期"]
    L --> M["更新订阅"]

    C -->|"否"| N["选择一个节点"]
    N --> O["切换到其他节点"]

    style A fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style K fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style J fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style I fill:#c8e6c9,stroke:#10B981,color:#10B981
    style M fill:#c8e6c9,stroke:#10B981,color:#10B981
    style O fill:#c8e6c9,stroke:#10B981,color:#10B981
    style B fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style D fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style F fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style H fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style L fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style N fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style C fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style E fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style G fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
Loading

Q8: 如何切换代理模式？

A: Zephyr 支持三种代理模式：

模式 说明 适用场景
规则模式 根据规则自动分流 日常使用（推荐）
全局模式 所有流量走代理 需要全部代理的场景
直连模式 所有流量直连 临时关闭代理

在主界面顶部可以快速切换模式。

Q9: 如何测试节点延迟？

A: Zephyr 提供多种延迟测试方式：

  1. 单个测试：右键点击节点 → 测试延迟
  2. 批量测试：选中多个节点或点击"全部测试"按钮
  3. URL 测试组：配置 URL 测试组后自动选择最低延迟节点

测试默认使用 http://www.gstatic.com/generate_204 作为测试 URL，可在设置中自定义。

Q10: 如何开启 TUN 模式？

A: TUN 模式可以接管系统所有流量（包括不支持代理设置的应用）：

  1. 进入 设置 → 网络设置
  2. 开启"TUN 模式"开关
  3. Windows：需要管理员权限，会自动安装虚拟网卡
  4. macOS：需要授予系统扩展权限
  5. Linux：需要 root 权限（sudo）

注意：TUN 模式与系统代理模式互斥，开启 TUN 后系统代理将自动关闭。

配置相关

Q11: 配置文件存放在哪里？

A: 配置文件位置因操作系统而异：

操作系统 路径
Windows %APPDATA%\zephyr\
macOS ~/Library/Application Support/zephyr/
Linux ~/.config/zephyr/

主要文件：

  • run_config.yaml - 主配置文件（位于 core/ 子目录）
  • profiles/ - 订阅配置文件目录
  • logs/ - 日志文件目录

Q12: 如何导入已有的 Clash 配置？

A: 有两种方式：

  1. 直接导入：将现有的 config.yaml 文件复制到 Zephyr 的 profiles/ 目录下
  2. 通过订阅：如果配置来自订阅链接，直接添加订阅 URL 即可

注意：Zephyr 使用 Mihomo 内核，与原版 Clash Meta 配置兼容，但部分 Clash Premium 特有功能可能不支持。

Q13: 如何自定义规则？

A: 你可以在订阅配置中添加自定义规则。Zephyr 支持以下规则类型：

rules:
  - DOMAIN-SUFFIX,google.com,Proxy
  - DOMAIN-KEYWORD,github,Proxy
  - IP-CIDR,192.168.0.0/16,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

规则按从上到下的顺序匹配，第一个匹配的规则生效。

Q14: DNS 设置推荐？

A: 推荐的 DNS 配置：

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

Q15: 如何设置规则分流？

A: Zephyr 支持通过规则实现智能分流。常见的分流策略：

  • 国内网站直连：GEOIP,CN,DIRECT
  • 流媒体走代理：DOMAIN-SUFFIX,netflix.com,Proxy
  • 广告拦截：DOMAIN-SUFFIX,ad.com,REJECT
  • 局域网直连：IP-CIDR,192.168.0.0/16,DIRECT

建议使用规则集 (Rule Provider) 来管理大量规则，便于维护和更新。

安全相关

Q16: Zephyr 会收集用户数据吗？

A: 不会。Zephyr 是完全本地运行的应用程序：

  • 不收集任何用户个人信息
  • 不上传使用数据到任何服务器
  • 不包含遥测 (Telemetry) 功能
  • 所有配置和日志仅存储在本地
  • 网络连接仅在你添加的代理节点和订阅服务器之间进行

你可以通过查看源代码或使用网络监控工具验证这一点。

Q17: 如何验证下载文件的完整性？

A: 每个 Release 都会附带 SHA256 校验和文件：

Windows (PowerShell):

Get-FileHash Zephyr_x.x.x_x64-setup.exe -Algorithm SHA256

macOS / Linux:

sha256sum Zephyr_x.x.x_x64.dmg

将计算结果与 Release 页面中的 checksums.txt 文件比对，一致则说明文件未被篡改。

Q18: 代理流量会被加密吗？

A: 加密取决于你使用的代理协议：

协议 加密 安全性
Shadowsocks 是 高
ShadowsocksR 是 中（已不推荐）
VMess 是 高
VLESS 可选 高（推荐配合 Reality）
Trojan 是（TLS） 高
Hysteria2 是（QUIC/TLS） 高
WireGuard 是 高

建议优先使用 VLESS+Reality、Trojan 或 Hysteria2 等现代协议。

Q19: 如何安全地分享配置？

A: 分享配置时请注意：

  1. 不要分享包含服务器地址、密码、UUID 的完整配置
  2. 分享规则配置时，移除所有代理节点信息
  3. 使用订阅链接而非配置文件分享（订阅通常有访问控制）
  4. 定期更换代理密码和 UUID

Q20: 发现安全漏洞如何报告？

A: 如果你发现了安全漏洞，请通过以下方式负责任地报告：

  1. 不要在公开 Issue 中披露漏洞详情
  2. 发送邮件至项目安全邮箱（见 GitHub 仓库 SECURITY.md）
  3. 或通过 GitHub Security Advisories 功能提交报告
  4. 我们会在 48 小时内回复，并在修复后公开致谢

开发相关

Q21: 如何从源码构建 Zephyr？

A: 请参考构建指南 (BuildGuide.md)。简要步骤：

# 克隆仓库
git clone https://github.com/zephyr-project/zephyr.git
cd zephyr

# 安装前端依赖
npm install

# 开发模式运行
npm run tauri dev

# 生产构建
npm run tauri build

Q22: 项目使用了哪些技术栈？

A:

层级 技术 说明
桌面框架 Tauri v2 轻量级桌面应用框架
前端 Vanilla JavaScript (ES Module) 原生 JavaScript，无框架依赖
样式 Tailwind CSS 原子化 CSS 框架
状态管理 无独立状态管理库 直接操作 DOM 与全局变量
后端 Rust 系统交互与代理管理
代理内核 Mihomo Clash Meta 内核

Q23: 如何调试 Tauri 后端代码？

A: 使用 VS Code 进行调试：

  1. 安装 rust-analyzer 和 CodeLLDB 扩展
  2. 使用 npm run tauri dev 启动开发模式
  3. 在 Rust 代码中设置断点
  4. 使用 VS Code 的"附加到进程"功能附加到 Tauri 进程
  5. 或使用 RUST_LOG=debug npm run tauri dev 查看详细日志

平台特定

Q24: Windows 上如何解除 UWP 应用代理限制？

A: Windows UWP 应用（如 Microsoft Store 应用）默认不使用系统代理。解决方法：

  1. 进入 设置 → 网络设置
  2. 开启"UWP 应用回环免除"
  3. 选择需要免除的 UWP 应用
  4. 或使用 Zephyr 内置的 UWP 解除工具（需要管理员权限）

注意：此功能需要管理员权限才能操作。

以下流程图展示了系统代理配置错误的完整诊断路径：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["代理不生效"] --> B{"Windows?"}
    B -->|"是"| C["检查注册表<br/>ProxyEnable=1"]
    B -->|"否"| D{"macOS?"}
    D -->|"是"| E["networksetup -getwebproxy<br/>检查代理配置"]
    D -->|"否"| F{"Linux?"}
    F -->|"是"| G["gsettings get<br/>org.gnome.system.proxy mode"]

    C --> H["检查代理地址<br/>是否为127.0.0.1"]
    E --> H
    G --> H

    H --> I["检查端口是否匹配"]
    I --> J["尝试禁用再启用"]
    J --> K["检查是否有其他<br/>代理软件冲突"]

    style A fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style K fill:#c8e6c9,stroke:#10B981,color:#10B981
    style C fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style E fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style G fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style H fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style I fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style J fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style B fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style D fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style F fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
Loading

Q25: Linux 上提示缺少共享库怎么办？

A: 不同发行版需要安装不同的依赖：

Ubuntu / Debian:

sudo apt update
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1 librsvg2-dev

Fedora:

sudo dnf install webkit2gtk4.1 gtk3 libappindicator-gtk3 librsvg2

Arch Linux:

sudo pacman -S webkit2gtk-4.1 gtk3 libappindicator-gtk3 librsvg

Q26: Connections 页面中的流量数据是如何计算的？

A: Connections 页面通过轮询 Mihomo API 的 /connections 端点获取连接列表。由于 Mihomo 返回的 download / upload 是连接建立以来的累计字节数，Zephyr 采用 delta 累积追踪算法：每次轮询时计算与上次的差值（dlDelta = max(0, curDl - prevDl)），除以时间间隔得到瞬时速率，同时累加得到总流量。Math.max(0, ...) 防御计数器重置异常。关闭的连接会保留在历史记录中（最多 200 条）。

Q27: Connections 页面的轮询会影响性能吗？

A: 轮询间隔为 2 秒，且仅在 Connections 页面可见时触发——切换到其他页面时自动暂停。页面离开时会通过 destroyConnectionsPage() 清理定时器和状态，不会产生后台开销。此外，escapeHtml() 内置 LRU 缓存（上限 500 条）优化了高频轮询下的重复转义性能。

如果以上内容未能解决你的问题，请在 GitHub Issues 中提交，并提供详细的环境信息和复现步骤。

导航

外部链接

Clone this wiki locally