#常见问题解答 (FAQ)

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

#目录

• 故障排除决策树
• 安装与启动
• 订阅
• 代理与连接
• TUN 模式
• 托盘、深链与更新
• 配置相关
• 日志
• 安全相关
• 开发相关
• 平台特定

#故障排除决策树

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

%%{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 -->|TUN| T[TUN 模式]

    C --> C1{症状?}
    C1 -->|首页显示「代理核心没有启动」| C2["点「查看日志」看原因<br/>修复后点「重试」"]
    C1 -->|窗口打不开/闪退| C3["检查 WebView2 / libwebkit2gtk<br/>查看应用日志"]
    C1 -->|macOS 提示已损坏| C4["xattr -cr 移除隔离属性"]

    D --> D1{症状?}
    D1 -->|首页显示「还没有添加订阅」| D2[添加订阅链接]
    D1 -->|订阅下载失败| D3["看错误原因<br/>检查链接/格式/网络"]
    D1 -->|没有节点| D4["确认是 Clash/Mihomo YAML<br/>而非纯节点链接列表"]

    E --> E1{症状?}
    E1 -->|系统代理开不了| E2["确认配置有 mixed/HTTP 端口"]
    E1 -->|开了也上不了网| E3["测延迟 → 换节点<br/>→ 切换模式"]
    E1 -->|部分应用不走代理| E4["改用 TUN<br/>或 UWP 环回免除"]

    T --> T1{平台?}
    T1 -->|Windows| T2["按提示以管理员身份重启"]
    T1 -->|macOS| T3["在密码框中授权"]
    T1 -->|Linux| T4["授予网络权限和策略规则"]

#安装与启动

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

A: 发布流水线为以下平台构建安装包：

不提供 32 位版本。Linux 提供 .deb、.rpm、.AppImage 和便携版 .tar.gz；Windows 还可以通过 winget（Juwan.Zephyr）和 Scoop 安装，Arch Linux 可以使用 AUR 包 zephyr-clash-bin。详见 Installation。

#Q2: Full 版、Lite 版和便携版有什么区别？

A:

首次使用推荐 Full 版。Lite 版适合想使用自己内核的用户：把内核可执行文件放入数据目录的 core/ 下，文件名为 zephyr-mihomo（Windows 为 zephyr-mihomo.exe；旧名 mihomo / mihomo.exe 也能识别）。数据目录位置见 Q24。

便携版需要程序目录中存在 .portable 标记文件；删除它后程序会改用系统应用数据目录。

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

A: Zephyr 是开源项目。Windows 的安装包（NSIS .exe、.msi）和便携版 exe 都由 SignPath Foundation 提供的证书进行 Authenticode 签名，可以先确认签名有效：

Get-ChildItem .\Zephyr_*.exe, .\Zephyr_*.msi -File -ErrorAction SilentlyContinue | Get-AuthenticodeSignature

状态应为 Valid，签名者为 SignPath Foundation（也可以右键文件 → 属性 → 数字签名查看）。确认无误后，如仍被误报，可将 Zephyr 安装目录加入杀毒软件白名单。更多校验方式见 Q30。

#Q4: 首页显示「代理核心没有启动」怎么办？

A: 这表示 Mihomo 内核启动失败，网络当前不经过代理。首页会显示一张错误卡片，包含：

• 内核返回的错误原文
• 查看日志：展开内核日志的最后 40 行，通常能直接看到原因（如配置语法错误、端口被占用）
• 重试：修复问题后点击，重新启动内核

卡片显示期间，首页其余区域会变暗且不可操作，状态栏显示「核心未运行，暂不可用」。常见原因：

如果当前配置无效或为空，Zephyr 会改用最小配置启动内核并提示「配置 '…' 无效或为空，正在使用最小配置。」，此时流量全部直连。

#Q5: 启动时闪退或窗口不出现怎么办？

A: 请按以下步骤排查：

1. 检查是否开启了「静默启动」（设置 → 通用）：开启后启动时只显示托盘图标，点击托盘图标即可打开窗口
2. Windows：确认已安装 WebView2 Runtime（便携版依赖系统已安装的 WebView2）
3. Linux：确认已安装 libwebkit2gtk-4.1 等依赖（见 Q38）
4. 从终端启动 Zephyr，查看错误输出
5. 若已开启应用日志持久化，查看数据目录下的 logs/app/（见 Q28）

%%{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{"托盘有图标?"}
    D -->|"有"| E["点击托盘图标<br/>(可能开启了静默启动)"]
    D -->|"没有"| F{"平台?"}
    F -->|"Windows"| G["安装 WebView2 Runtime"]
    F -->|"Linux"| H["安装 libwebkit2gtk-4.1 等依赖"]
    F -->|"macOS"| I["xattr -cr /Applications/Zephyr.app"]

    style A fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style C fill:#c8e6c9,stroke:#10B981,color:#10B981
    style E fill:#c8e6c9,stroke:#10B981,color:#10B981
    style B fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style D fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style F fill:#fff3e0,stroke:#F59E0B,color:#F59E0B

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

A: macOS 版本没有 Apple 签名与公证，Gatekeeper 会拦截从网络下载的应用。移除隔离属性即可：

xattr -cr /Applications/Zephyr.app

也可以在 系统设置 → 隐私与安全性 中对 Zephyr 选择「仍要打开」。

#订阅

#Q7: 首次启动显示「还没有添加订阅」，系统代理开关点了没反应？

A: 没有任何订阅时，内核以最小配置运行（所有流量 MATCH,DIRECT），开启系统代理也只会直连。因此：

• 首页（极简模式）和控制台的流量卡片会显示「还没有添加订阅」和 添加订阅 按钮
• 系统代理状态提示「添加订阅后即可开启」
• 点击系统代理开关（首页或控制台）不会开启代理，而是打开 订阅管理 → 添加订阅 对话框
• 系统代理的全局快捷键同样不会开启，只提示「添加订阅后即可开启」

添加第一个订阅（包括通过 clash:// 深链导入）后，Zephyr 会自动启用它并重启内核，空状态随之消失。

#Q8: 支持哪些订阅格式？添加后没有节点怎么办？

A: Zephyr 需要 Clash / Mihomo YAML 格式的订阅（包含 proxies: 或 proxy-groups:）。整体经过 Base64 编码的 YAML 也能自动解码。纯节点链接列表（如每行一个 ss://、vmess://、trojan:// 链接，或其 Base64 编码）不会被转换，下载时会报「The subscription content is neither a valid Clash YAML nor a supported node list」。请向服务商索取 Clash / Mihomo 格式的订阅链接。

没有节点时可依次检查：

1. 订阅已过期或服务端异常：返回空内容时会报「Subscription returned empty content」
2. 格式不对：见上文
3. User-Agent：部分服务商按 User-Agent 返回不同格式或拒绝未知客户端。默认 UA 为 Zephyr/<版本号>；可以在订阅的编辑面板中为单个订阅设置 UA（面板中有说明），也可以在 设置 → 订阅与规则 中开启「启用订阅客户端伪装」并选择客户端类型
4. 点击订阅卡片上的更新按钮手动刷新；卡片会显示上次更新失败的原因（鼠标悬停查看详情）

#Q9: 订阅下载失败，提示网络错误或被拦截？

A: Zephyr 下载订阅时不会使用系统代理或环境变量中的代理，而是按顺序尝试：

1. 直连
2. 通过 Zephyr 自己运行中的内核（内核的本地监听端口）
3. 临时切换到全局模式：选用一个可用节点下载，完成后自动恢复原来的模式和节点选择（若下载期间你自己改了模式或节点，则不会覆盖你的选择）

整个过程有约 14 秒的总时限。同时还有以下安全限制（触发时报 SSRF 相关错误）：

• 只接受 http:// / https:// 链接
• 订阅域名解析到私有、回环或 Fake-IP 地址时会被拒绝；重定向到内网地址同样被拦截（最多跟随 5 次重定向）
• 你直接输入的内网地址（如 http://192.168.1.10/sub）或单标签内网主机名会被允许，但只走直连
• Fake-IP 网段中的地址（如 198.18.x.x）永远不会被当作订阅地址

多个订阅同时更新时，下载会排队依次进行。

#Q10: 订阅中的某些字段为什么被删掉了？

A: 为防止订阅或导入的配置打开额外的控制入口，Zephyr 会在保存前清洗配置，移除：

• external-controller-unix、external-controller-pipe、external-controller-tls、external-controller-cors、external-doh-server、external-ui、external-ui-url、external-ui-name（包括通过 YAML << 合并键带入的）
• script、script-path 以及 cfw-* 等 Clash for Windows 专有字段
• proxy/rule provider 中的 path（防止路径穿越）

external-controller 和 secret 由 Zephyr 自己管理（控制器固定在本机回环地址，并使用 Zephyr 生成的密钥）。规则库文件和 Prism 覆写也经过同样的清洗；无法解析的 YAML 会直接报错，而不含危险字段的内容会原样保存（保留注释）。

#代理与连接

#Q11: 开不了系统代理，提示「内核没有 HTTP 代理端口」？

A: 系统代理需要一个 HTTP 监听端口。Zephyr 只使用当前配置中的 mixed-port 或 port，不会回退到 socks-port 或硬编码的 7890（否则其他应用的 HTTP 流量会被导向一个无法使用的地址）。请在 设置 → 网络 → 端口设置 中启用混合端口，或在配置中设置 mixed-port。系统代理只允许指向本机回环地址。

#Q12: 代理开启后无法上网？

A: 按以下顺序排查：

1. 确认已添加订阅并选择了一个可用节点
2. 测试节点延迟，排除超时的节点
3. 确认系统代理指向 127.0.0.1:<混合端口>（默认混合端口为 7890）
4. 切换代理模式（规则 / 全局 / 直连）
5. 检查防火墙或其他代理软件是否冲突
6. 不读取系统代理设置的应用请改用 TUN 模式

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["无法上网"] --> B{"已添加订阅?"}
    B -->|"否"| B1["添加订阅"]
    B -->|"是"| C["测试节点延迟"]
    C --> D{"延迟正常?"}
    D -->|"否"| E["更新订阅 / 换节点"]
    D -->|"是"| F["检查系统代理<br/>127.0.0.1:混合端口"]
    F --> G{"设置正确?"}
    G -->|"否"| H["关闭再开启系统代理"]
    G -->|"是"| I["切换模式<br/>规则/全局/直连"]
    I --> J["检查防火墙或<br/>其他代理软件冲突"]

    style A fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style B1 fill:#c8e6c9,stroke:#10B981,color:#10B981
    style E fill:#c8e6c9,stroke:#10B981,color:#10B981
    style J fill:#c8e6c9,stroke:#10B981,color:#10B981
    style B fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style D fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style G fill:#fff3e0,stroke:#F59E0B,color:#F59E0B

#Q13: Zephyr 退出或崩溃后，系统代理会被恢复吗？

A: Zephyr 用一个"所有权标记"记录系统代理是否由它开启：

• 通过托盘「退出」正常退出：关闭系统代理并清除标记，不会留下指向已停止内核的代理
• 异常退出 / 崩溃后再次启动：如果标记还在，Zephyr 会把系统代理恢复到当前内核正在监听的端口（而不是旧端口）
• 其他程序设置的系统代理：Zephyr 不会把它当成自己的，也不会覆盖或关闭它

关闭窗口默认只是隐藏到托盘（设置 → 通用 → 关闭时隐藏到托盘），内核和代理仍在运行。开启「轻量模式」后，关闭窗口会销毁界面以释放内存，点击托盘即可恢复。

#Q14: 如何切换代理模式？

A: Zephyr 支持三种模式：

可在首页、控制台、托盘菜单或全局快捷键中切换。直连模式下，代理节点页会显示说明面板和切回按钮。

#Q15: 如何测试节点延迟？

A:

1. 全部测试：代理节点页的测速按钮；测试中按钮变为停止方块，可随时中断（未完成的节点保持原值）。测完后会显示结果行，并提供一键切换到最快节点（不计入 DIRECT、REJECT 和代理组）
2. 单个测试：节点卡片上的「重新测试这个节点」按钮
3. 隐藏超时节点：测速后可使用「隐藏超时」过滤不可用节点

延迟测试通过 Mihomo 的 /proxies/:name/delay 接口进行，测试地址固定为 https://www.gstatic.com/generate_204，单次超时 5 秒。

#Q16: 自动切换节点、节点评分和定时测速有什么区别？

A: 三者位于 设置 → 代理，是相互独立的开关：

定时测速只为评分提供数据，因此关闭节点评分时定时测速会一并停用。保存失败的开关会自动恢复为实际生效的状态。

#TUN 模式

#Q17: 如何开启 TUN 模式？

A: TUN 模式通过虚拟网卡接管系统流量，包括不读取系统代理设置的应用。开关位于首页（极简与控制台模式均有）和托盘菜单。各平台需要的权限不同：

开启 TUN 时，Zephyr 会确保配置中的 dns-hijack 同时包含 UDP 与 TCP 的 53 端口，把 DNS 查询交给 Mihomo，防止 DNS 泄漏。TUN 与系统代理可以同时开启；托盘图标此时显示 TUN 状态。

#Q18: Windows 上开启 TUN 有哪些注意事项？

A:

• 需要管理员账户：以管理员身份重启只对属于管理员组的账户提供（UAC 弹出的是「是/否」确认）。标准账户会提示「TUN 模式需要管理员权限，而当前 Windows 账户不是管理员」——此时用其他管理员的凭据提权会让 Zephyr 以那个用户身份运行、读取那个用户的配置，所以不会提供重启选项
• 取消 UAC：提示「授权已取消」，TUN 保持关闭
• 之后普通启动：TUN 偏好只在以管理员身份运行时生效。下次未提权启动时，Zephyr 会以 TUN 关闭的状态启动（即使配置文件里写了 tun.enable: true），开关再次点击时会重新询问是否以管理员身份重启
• 已经是管理员仍然失败：提示「开启 TUN 失败，详情见内核日志」，请查看内核日志
• 系统代理：以管理员身份重启前开启的系统代理，会在提权后的新实例中恢复
• 提权运行期间再次打开 Zephyr：普通启动会把参数（例如 clash:// 链接）交给正在运行的管理员实例，而不会再启动一个新实例

#Q19: TUN 开启失败或提示偏好设置保存失败？

A: 常见提示及含义：

macOS 上 root 内核的日志写入 /Library/Logs/Zephyr/tun.log。

#托盘、深链与更新

#Q20: 托盘图标和菜单有哪些状态？

A: 托盘图标有三种状态：

托盘菜单包含：显示窗口、系统代理、TUN、规则/全局/直连模式、订阅切换、节点切换、复制代理环境变量（格式可在设置中选择）以及退出。在托盘中选择的节点会记录到当时运行的配置上，重启后同样会恢复；有其他网络操作（如订阅更新、TUN 切换）进行中时，托盘的节点和订阅切换会被拒绝。

#Q21: 如何通过 clash:// 链接导入订阅？

A: Zephyr 支持如下格式的深链：

clash://install-config?url=<URL 编码的订阅地址>&name=<URL 编码的名称>

• 只接受 http:// / https:// 订阅地址，且必须包含主机名；地址最长 2048 个字符
• name 中可能导致路径穿越或非法文件名的字符会被替换为 _，最长 128 个字符
• 导入前一定会弹出确认对话框，显示名称和地址；确认后才开始下载
• 窗口隐藏在托盘时会自动显示并弹出确认
• 启动时随命令行传入，或在页面加载期间到达的链接会排队保存（最多 8 条），页面就绪后按顺序逐条确认
• 如果这是第一个订阅，导入后会自动启用

注意：v2.5.0 的安装包配置中没有向系统注册 clash:// 协议。如果在浏览器中点击 clash:// 链接没有反应，可以复制链接中的订阅地址，在 订阅管理 → 添加订阅 中手动添加。

#Q22: 如何检查和安装更新？

A: 在 设置 → 关于 → 检查更新 打开更新对话框，它会依次显示：检查中 → 已是最新 / 有可用更新（显示版本与更新说明）→ 下载进度 → 完成或失败（可重试）。

• 内核更新：下载后进行 SHA256 校验，替换前备份旧内核；新内核启动失败时自动回滚。更新完成后会重新应用 Prism 补丁、已启用的覆写和节点选择
• 应用更新：下载安装包后校验 SHA256 和 Minisign 签名，任一失败都会删除安装包；校验通过后打开安装程序
• 两者都有更新：先更新内核，再打开应用安装程序
• 便携版：无法自动更新应用，对话框提供「前往发布页」；如内核也有更新，可选择「仅更新内核」
• 检查失败（例如无法读取已安装的内核版本）会显示为失败，而不是"已是最新"
• 更新对话框中的链接会在系统浏览器中打开

在 设置 → 关于 中可开启「自动检查内核更新」和「自动检查应用更新」：启动后数秒检查一次，有更新时只发出通知，不会自动安装。

更新相关的网络请求只发往 GitHub（github.com、api.github.com、objects.githubusercontent.com），先直连，失败时经 Zephyr 自己的内核重试，不使用系统或环境变量中的代理。

#配置相关

#Q23: 设置页有哪些分区？

A: 设置页包含：外观、通用、代理、网络、订阅与规则、数据与安全、关于。页面顶部的搜索框可以过滤设置项，右侧的分区标记可快速跳转。「高级设置」页面提供内核配置（直接修改运行中的内核并写入当前配置）和自定义启动参数。「恢复默认值」会在确认对话框中列出将被重置和保留的内容。

#Q24: 配置文件存放在哪里？

A: 安装版使用 Tauri 的应用数据目录（应用标识为 com.zephyr.desktop）：

便携版使用程序所在目录。主要内容：

在 设置 → 数据与安全 → 配置文件夹 中可以直接打开该目录；「备份与恢复」可导出或导入配置。

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

A:

1. 订阅链接：在 订阅管理 中添加 URL（添加对话框会实时校验链接）
2. 本地文件：把 .yaml / .yml 文件直接拖入 Zephyr 窗口，会被导入到 profiles/ 目录（导入时同样经过安全清洗）；设置 → 数据与安全 → 配置文件夹 可以打开该目录。本地配置在订阅管理中同样显示为卡片，可重命名或补充订阅链接

Zephyr 使用 Mihomo 内核，兼容 Clash Meta 配置，部分 Clash Premium 特有功能可能不支持。导入的配置同样会经过安全清洗。订阅和覆写卡片可以通过拖动手柄或 Alt + ↑/↓ 调整顺序。

#Q26: 如何自定义规则？

A: 推荐使用 规则管理 页的规则库（Prism .prism.yaml 规则文件），无需修改订阅本身：可以新增规则文件、在列表内直接插入和编辑规则（新规则默认使用该文件最近使用的策略）、为订阅启用或停用规则文件。Mihomo 支持的常见规则写法：

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

规则按从上到下的顺序匹配，第一条命中的规则生效。也可以使用 Prism 覆写（Prism DSL 或 JavaScript）对配置做更复杂的修改，详见 Configuration。如果切换规则文件后内核拒绝重新加载，Zephyr 会提示需要重启内核才能生效。

#Q27: DNS 如何设置？「DNS 防泄漏」做了什么？

A: 设置 → 网络 中的 DNS 防泄漏 开关会接管系统 DNS，避免查询绕过代理。开启后，Zephyr 在运行时向内核下发以下 DNS 配置（不会写入订阅文件，因此不会破坏订阅自带的 DNS 配置）：

sniffing: true
dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.0/16
  fake-ip-filter: ['*.lan', '*.local', '*.localhost', '*.localdomain', 'stun.*', ...]  # 局域网、游戏主机、连通性检测等
  default-nameserver: [223.5.5.5, 119.29.29.29, 1.1.1.1, 8.8.8.8]
  nameserver:   # 默认值，可通过开关旁的「服务器」按钮修改
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query

每次内核重启或配置重新加载后，该设置会自动重新应用。关闭开关则使用订阅或配置文件自身的 DNS 设置。

#日志

#Q28: 日志存放在哪里？

A: 日志页（运行日志）有「内核日志」和「应用日志」两个标签。内核日志的文件位置取决于是否开启持久化：

开启「保存应用日志」后，应用日志写入数据目录下的 logs/app/。两项开关在日志页的「设置」中，另可设置保留天数（1–30 天，默认 3 天）和单文件大小上限（1–500 MB，默认 50 MB）；「导出…」可按日期导出日志。Zephyr 不对内核日志内容进行修改。

#Q29: 日志页如何筛选？会影响性能吗？

A: 内核日志和应用日志共用同一个筛选栏：日志级别、行数显示和搜索（搜索命中会高亮，支持包含 <、& 等特殊字符的查询）。「仅错误」同时包含 fatal 级别；Prism 事件失败也计为错误。向上滚动时停止自动跟随，底部的跳转按钮会显示新增行数。

性能方面：日志页按需加载，离开页面时停止轮询；轮询间隔 1 秒，上一次读取未完成时跳过本次；内存中最多保留 2000 行（环形缓冲区），列表使用虚拟滚动。

#安全相关

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

A: 发布页的每个文件都附带一个同名的 .minisig 签名文件（Minisign / Ed25519）。使用 minisign 和 Zephyr 的公钥验证：

minisign -Vm Zephyr_2.5.0_x64-setup-full.exe \
  -P RWRkVQqGWolsGBbhZRpFQ3sPG/i4A2dGlf2E0NXJvZAviVd/I+sUzw1Z

也可以将文件的 SHA256 与 GitHub Release 页面中该文件显示的 SHA256 摘要比对：

Windows (PowerShell):

Get-FileHash .\Zephyr_2.5.0_x64-setup-full.exe -Algorithm SHA256

macOS / Linux:

shasum -a 256 Zephyr_2.5.0_aarch64-full.dmg   # Linux 可用 sha256sum

Windows 安装包还可以检查 Authenticode 签名，见 Q3。每个 Release 还附带 CycloneDX 格式的 SBOM（软件物料清单）。

#Q31: Zephyr 会收集用户数据吗？

A: 不会。Zephyr 不包含遥测功能，不收集个人信息，配置和日志只保存在本地。Zephyr 自身发起的网络请求只有：

• 你添加的订阅地址、规则提供者等配置中的资源
• 你通过代理节点访问的流量
• 检查/下载更新（内核、Geo 数据、应用，均来自 GitHub）
• 开启订阅 User-Agent 伪装时，查询 Clash Verge、Mihomo Party、FlClash 在 GitHub 上的最新版本号，用于生成 UA

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

#Q32: 代理流量会被加密吗？

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

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

#Q33: 如何安全地分享配置？

A:

1. 不要分享包含服务器地址、密码、UUID 的完整配置或订阅链接
2. 分享规则时，只导出规则文件，移除所有代理节点信息
3. 分享日志前检查其中是否含有订阅地址或节点信息
4. 「加密配置文件」（设置 → 数据与安全）使用机器密钥加密配置，加密后的文件无法在其他设备上使用

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

A: 请负责任地披露：

1. 不要在公开的 Issue、Discussion 或 PR 中披露漏洞详情
2. 首选 GitHub 私密漏洞报告：仓库 Security 页 → Report a vulnerability
3. 无法使用时，发送邮件至 [email protected]，标题格式 [SECURITY REPORT] <漏洞摘要>（支持中文和英文）
4. 维护者会在 48 小时内确认收到；修复发布时会在安全公告和 Release Notes 中致谢

详见 SECURITY.md 和 Security。

#开发相关

#Q35: 如何从源码构建 Zephyr？

A: 需要 Rust 1.96.0、Node.js ≥ 20.18.1 和 pnpm 10。详见 BuildGuide，简要步骤：

# 克隆仓库
git clone https://github.com/Juwan-Hwang/Zephyr.git
cd Zephyr

# 安装依赖
pnpm install

# 开发模式运行
pnpm dev

# 生产构建
pnpm build

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

A:

#Q37: 如何调试和参与贡献？

A:

1. 使用 pnpm dev 启动开发模式，前端改动会被热更新
2. Rust 侧推荐 VS Code + rust-analyzer + CodeLLDB，附加到 Zephyr 进程设置断点
3. 应用内的「运行日志 → 应用日志」可以查看后端事件
4. 提交前运行 lint、类型检查、i18n 检查和测试；如何添加翻译、编写测试以及 CI 的要求见 Contributing

#平台特定

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

A: .deb / .rpm 安装包会声明依赖，由包管理器自动安装。使用 AppImage 或便携版时，请手动安装：

Ubuntu / Debian:

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

Fedora:

sudo dnf install webkit2gtk4.1 gtk3 libayatana-appindicator-gtk3

Arch Linux:

sudo pacman -S webkit2gtk-4.1 gtk3 libayatana-appindicator

#Q39: Windows 上 UWP / 商店应用不走代理怎么办？

A: Windows UWP 应用（如 Microsoft Store 应用）默认禁止访问本机回环地址，因此无法使用本地代理。在 设置 → 网络 → UWP 环回免除 中点击执行：这会对所有 UWP 应用应用环回免除，需要管理员权限。也可以改用 TUN 模式。

以下流程图展示了系统代理不生效时的诊断路径：

%%{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["GNOME: gsettings get org.gnome.system.proxy mode<br/>KDE / XFCE: 检查桌面代理设置"]

    C --> H["代理地址应为<br/>127.0.0.1:混合端口"]
    E --> H
    G --> H

    H --> J["关闭再开启系统代理"]
    J --> K["检查是否有其他<br/>代理软件冲突"]
    K --> L["应用不读取系统代理<br/>→ 改用 TUN"]

    style A fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style L 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 J fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style K 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

#Q40: 连接详情页为什么能显示应用图标？读取图标安全吗？

A: Zephyr 默认为内核设置 find-process-mode: always（配置中未指定时），Mihomo 会报告每条连接的来源程序路径，连接详情页据此显示该应用的真实图标：

• Windows：可执行文件内嵌的图标
• macOS：所在 .app 包的图标（支持 XML 与二进制 Info.plist）
• Linux：匹配的 .desktop 条目或 Flatpak 应用 ID 对应的图标（hicolor 主题与 pixmaps）

找不到图标时显示中性的应用占位图标。读取图标时不会访问网络共享、映射的网络驱动器或网络挂载（NFS/SMB、sshfs 等），路径上的符号链接会逐级解析检查；在 Linux 上也不会把一个应用的图标错配给共用解释器（如 java、python）或共享目录的其他程序。已找到的图标在本次运行期间缓存，找不到的会在稍后重新尝试。

#Q41: 连接详情页的流量数据是如何计算的？

A: 连接详情页轮询 Mihomo API 的 /connections 端点获取连接列表。Mihomo 返回的 download / upload 是连接建立以来的累计字节数，Zephyr 每次轮询计算与上次的差值（dlDelta = max(0, curDl - prevDl)），除以时间间隔得到实时速率，并累加得到总流量；Math.max(0, ...) 用于防御计数器重置。已关闭的连接保留在历史记录中（最多 200 条）。悬停某一行可以直接关闭该连接。

#Q42: 连接详情页的轮询会影响性能吗？

A: 内核可达时每 2 秒轮询一次，不可达时放慢到每 15 秒；只有在连接详情页可见且窗口未隐藏时才轮询，切换页面或隐藏窗口后自动暂停，离开页面时会清理定时器。你也可以手动「暂停」刷新（暂停状态在回到窗口后保持）。表格按连接 ID 增量更新，只修改变化的行。

如果以上内容未能解决你的问题，请在 GitHub Issues 中提交，并提供详细的环境信息、界面提示原文和复现步骤（见 Contributing 的 Issue 提交指南）。