Skip to content

Installation

Jump to bottom
Juwan-Hwang edited this page Apr 11, 2026 · 4 revisions

安装指南

本指南将帮助你选择合适的 Zephyr 版本并完成安装。Zephyr 是基于 Tauri v2 的 Mihomo GUI 代理客户端，支持 Windows、macOS 和 Linux 三大平台。

目录

版本选择

Zephyr 提供两个版本，请根据你的情况选择：

%%{init: {'themeVariables': {'fontSize': '10px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '10px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 15, 'rankSpacing': 25}}}%%
graph LR
    A{首次安装 Zephyr?} -->|是| B[下载 Full 版<br/>内置 Mihomo 内核<br/>开箱即用]
    A -->|否| C{已有 Mihomo 内核<br/>或想自定义内核?}
    C -->|是| D[下载 Lite 版<br/>不含内核<br/>体积更小]
    C -->|否| B

    B --> E[前往 GitHub Releases<br/>下载对应平台安装包]
    D --> E

    E --> F{选择平台}
    F -->|Windows| G[.exe 安装包<br/>或 .msi]
    F -->|macOS| H{芯片类型}
    H -->|Intel| I[.dmg x64]
    H -->|Apple Silicon| J[.dmg ARM64]
    F -->|Linux| K[.deb / .rpm / .AppImage]
Loading

版本对比

特性 Full 版 Lite 版
Mihomo 内核 内置最新稳定版 不含
安装包大小 ~30MB ~8MB
首次使用 无需额外配置 需手动放置内核文件
内核更新 随应用更新 自行管理
适用人群 新用户、普通用户 高级用户、自定义需求

推荐：如果你不确定选哪个，请选择 Full 版。

系统要求

在安装之前，请确认你的系统满足以下最低要求：

基础要求

组件 最低要求 推荐配置
CPU x64 双核处理器 x64 四核或 ARM64
内存 2 GB RAM 4 GB RAM
磁盘空间 100 MB 200 MB
网络 需要网络连接（用于订阅更新） 稳定的网络连接

操作系统要求

操作系统 最低版本 推荐版本 架构
Windows Windows 10 1809 (Build 17763) Windows 11 23H2 x64
macOS macOS 10.13 High Sierra macOS 14 Sonoma x64, ARM64
Ubuntu 20.04 LTS 22.04 LTS x64
Fedora 36 40 x64
Arch Linux 滚动更新 (最新) 滚动更新 (最新) x64

运行时依赖

平台 依赖 说明
Windows WebView2 Runtime Windows 11 已内置，Windows 10 需单独安装
macOS 无额外依赖 系统自带所需框架
Linux libwebkit2gtk-4.1-0 Web 渲染引擎
Linux libgtk-3-0 GTK3 图形库
Linux libayatana-appindicator3-1 系统托盘图标
Linux librsvg2 SVG 图标渲染

环境搭建流程

下图展示了从准备安装到完成安装的完整流程：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["准备安装"] --> B{"操作系统?"}

    B -- "Windows" --> C["检查 WebView2 Runtime"]
    C --> D{"已安装?"}
    D -- "否" --> E["下载安装 WebView2"]
    E --> F["下载 Zephyr 安装包"]
    D -- "是" --> F

    B -- "macOS" --> G["检查 macOS 版本<br/>(>= 10.13 High Sierra)"]
    G --> H["下载对应芯片 DMG<br/>Intel / Apple Silicon"]

    B -- "Linux" --> I["检查发行版"]
    I -- "Ubuntu / Debian" --> J["安装 libwebkit2gtk 等依赖<br/>apt install"]
    I -- "Fedora" --> K["安装依赖<br/>dnf install"]
    I -- "Arch Linux" --> L["安装依赖<br/>pacman -S"]
    J --> M["下载对应格式包"]
    K --> M
    L --> M

    F --> N["运行安装程序"]
    H --> N
    M --> N

    N --> O{"Windows Defender<br/>拦截?"}
    O -- "是" --> P["添加白名单<br/>更多信息 → 仍要运行"]
    P --> Q["安装完成"]
    O -- "否" --> Q

    style A fill:#3498db,stroke:#2980b9,color:#fff
    style Q fill:#2ecc71,stroke:#27ae60,color:#fff
    style P fill:#f39c12,stroke:#e67e22,color:#fff
    style E fill:#f39c12,stroke:#e67e22,color:#fff
Loading

Windows 安装

方式一：安装包安装 (.exe)

  1. 前往 GitHub Releases 页面
  2. 下载 Zephyr_x.x.x_x64-setup-full.exe（Full 版）或 Zephyr_x.x.x_x64-lite-setup.exe（Lite 版）
  3. 双击运行安装程序
  4. 如果 Windows Defender 弹出提示，点击"更多信息" → "仍要运行"
  5. 选择安装目录（默认 C:\Program Files\Zephyr\）
  6. 勾选"创建桌面快捷方式"（可选）
  7. 点击"安装"并等待完成
  8. 点击"完成"启动 Zephyr

方式二：MSI 安装包

  1. 下载 Zephyr_x.x.x_x64_en-US.msi
  2. 双击运行 MSI 安装包
  3. 按照安装向导完成安装

方式三：便携版

注意：便携版 (.zip) 可能未提供，请以 GitHub Releases 页面实际发布的文件为准。Tauri 构建配置目前仅包含 NSIS 和 MSI 安装包目标。

  1. 下载 Zephyr_x.x.x_x64_portable.zip
  2. 解压到任意目录
  3. 运行 Zephyr.exe

注意：便携版不会自动创建快捷方式，也不会写入注册表。

Lite 版内核放置

如果使用 Lite 版，需要手动放置 Mihomo 内核：

  1. 从 Mihomo Releases 下载对应平台的内核
  2. 将内核文件重命名为 mihomo.exe（Windows）
  3. 放置到 Zephyr 安装目录下

macOS 安装

方式一：DMG 安装（推荐）

  1. 前往 GitHub Releases 页面
  2. 根据芯片类型选择下载：
    • Apple Silicon (M1/M2/M3/M4)：Zephyr_x.x.x_aarch64-full.dmg
    • Intel：Zephyr_x.x.x_x64-full.dmg
  3. 双击打开 DMG 文件
  4. 将 Zephyr 图标拖入 Applications 文件夹
  5. 首次打开时，如果提示"已损坏"，执行以下命令：
xattr -cr /Applications/Zephyr.app
  1. 在"系统设置 → 隐私与安全性"中点击"仍要打开"

方式二：Homebrew 安装

注意：Zephyr 目前未发布到 Homebrew，以下命令暂不可用。请使用 DMG 方式安装。

# brew install --cask zephyr  # 暂不可用

Lite 版内核放置

  1. 下载 Mihomo macOS 版本内核
  2. 将内核文件重命名为 mihomo（无扩展名）
  3. 放置到 /Applications/Zephyr.app/Contents/MacOS/ 目录下
  4. 赋予执行权限：
chmod +x /Applications/Zephyr.app/Contents/MacOS/mihomo

Linux 安装

Ubuntu / Debian (.deb)

# 下载 .deb 包
wget https://github.com/Juwan-Hwang/Zephyr/releases/download/v0.1.0/Zephyr_0.1.0_amd64.deb

# 安装
sudo dpkg -i Zephyr_0.1.0_amd64.deb

# 如果提示缺少依赖，执行
sudo apt-get install -f

Fedora / RHEL (.rpm)

# 下载 .rpm 包
wget https://github.com/Juwan-Hwang/Zephyr/releases/download/v0.1.0/Zephyr-0.1.0.x86_64.rpm

# 安装
sudo dnf install Zephyr-0.1.0.x86_64.rpm

Arch Linux (AUR)

# 使用 yay
yay -S zephyr-bin

# 或使用 paru
paru -S zephyr-bin

AppImage（通用）

# 下载 AppImage
wget https://github.com/Juwan-Hwang/Zephyr/releases/download/v0.1.0/Zephyr-0.1.0-x86_64.AppImage

# 赋予执行权限
chmod +x Zephyr-0.1.0-x86_64.AppImage

# 运行
./Zephyr-0.1.0-x86_64.AppImage

安装系统依赖

在运行 Zephyr 之前，确保已安装所需的系统依赖：

Ubuntu / Debian:

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

Fedora:

sudo dnf install webkit2gtk4.1 gtk3 libappindicator-gtk3 librsvg2 openssl-devel

Arch Linux:

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

Lite 版内核放置

  1. 下载 Mihomo Linux 版本内核
  2. 将内核文件重命名为 mihomo（无扩展名）
  3. 放置到 /opt/zephyr/ 或 Zephyr 安装目录下
  4. 赋予执行权限：
chmod +x /opt/zephyr/mihomo

首次使用流程

安装完成后，按照以下流程快速上手 Zephyr：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A[启动 Zephyr 应用] --> B[添加订阅链接<br/>点击「订阅管理」→「添加」]
    B --> C[更新订阅<br/>点击「更新」按钮获取节点列表]
    C --> D[选择代理节点<br/>在节点列表中选择一个节点]
    D --> E[开启系统代理<br/>点击主界面的开关按钮]
    E --> F{需要接管所有流量?}
    F -->|是| G[开启 TUN 模式<br/>设置 → 网络设置 → TUN 模式]
    F -->|否| H[使用系统代理模式<br/>已自动配置系统代理]
    G --> I{Windows UWP 应用<br/>需要代理?}
    H --> I
    I -->|是| J[开启 UWP 免除<br/>设置 → 网络设置 → UWP 回环免除]
    I -->|否| K[配置完成<br/>开始使用]
    J --> K
Loading

详细步骤

第 1 步：启动应用

安装完成后，从桌面快捷方式或应用菜单启动 Zephyr。首次启动时会显示欢迎页面。

第 2 步：添加订阅

  1. 点击左侧导航栏的"订阅管理"
  2. 点击"添加订阅"按钮
  3. 输入你的订阅链接 URL
  4. 可选：设置自动更新间隔（推荐 6 小时）
  5. 点击"保存"

第 3 步：更新订阅并选择节点

  1. 在订阅列表中点击"更新"按钮
  2. 等待节点列表加载完成
  3. 在"代理"页面中浏览可用节点
  4. 点击选择一个延迟较低的节点
  5. 可选：使用"延迟测试"功能批量测试节点

第 4 步：开启系统代理

  1. 返回主界面
  2. 点击顶部的系统代理开关
  3. 确认系统代理已设置为 127.0.0.1:7890
  4. 打开浏览器测试连接

第 5 步（可选）：开启 TUN 模式

如果你需要代理不支持代理设置的应用（如游戏、命令行工具等）：

  1. 进入"设置" → "网络设置"
  2. 开启"TUN 模式"开关
  3. 根据提示授予相应权限
  4. TUN 模式会创建虚拟网卡接管所有流量

第 6 步（可选）：UWP 应用免除（仅 Windows）

如果你需要 Microsoft Store 应用走代理：

  1. 进入"设置" → "网络设置"
  2. 开启"UWP 回环免除"
  3. 在弹出的列表中选择需要免除的应用
  4. 需要管理员权限

常见安装问题

Q: Windows 安装时提示"缺少 WebView2 Runtime"

A: Zephyr 依赖 Microsoft Edge WebView2 Runtime。Windows 11 已内置，Windows 10 需要手动安装：

  1. 访问 WebView2 下载页面
  2. 下载并安装"Evergreen Standalone Installer"
  3. 重新运行 Zephyr 安装程序

Q: macOS 提示"无法验证开发者"

A: 由于 Zephyr 未购买 Apple 开发者签名证书，需要手动允许：

  1. 双击应用后提示"无法打开"
  2. 进入"系统设置" → "隐私与安全性"
  3. 在底部找到"仍要打开"按钮，点击确认
  4. 或使用终端命令：xattr -cr /Applications/Zephyr.app

Q: Linux 启动时提示缺少共享库 (.so)

A: 请安装对应的系统依赖。参见上方"安装系统依赖"章节中针对你发行版的安装命令。

你也可以使用以下命令诊断缺少的库：

ldd /opt/zephyr/zephyr | grep "not found"

Q: 安装后无法连接网络

A: 请检查：

  1. 确认已添加订阅并更新了节点列表
  2. 确认已选择一个可用节点
  3. 测试节点延迟，排除不可用节点
  4. 检查防火墙是否阻止了 Zephyr
  5. 尝试切换代理模式

Q: 如何卸载 Zephyr？

A:

平台 卸载方式
Windows 设置 → 应用 → 已安装的应用 → 找到 Zephyr → 卸载
macOS 将 /Applications/Zephyr.app 拖入废纸篓
Linux (deb) sudo dpkg -r zephyr
Linux (rpm) sudo dnf remove zephyr
Linux (AUR) yay -R zephyr-bin

配置文件和日志不会被自动删除，如需彻底清理请手动删除配置目录（参见 FAQ.md 中的配置文件路径）。

Q: 如何更新 Zephyr？

A:

  • Windows：Zephyr 支持自动更新，启动时会检查新版本并提示下载安装
  • macOS：支持自动更新，或重新下载最新 DMG 覆盖安装
  • Linux：通过包管理器更新（apt upgrade / dnf upgrade / yay -Su）或重新下载安装

安装完成后，建议阅读 FAQ.md 了解更多使用技巧，或阅读 BuildGuide.md 了解如何从源码构建。

导航

外部链接

Clone this wiki locally