#安装指南

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

#目录

• 版本选择
• 系统要求
• 下载与校验
• Windows 安装
• macOS 安装
• Linux 安装
• 便携版
• Lite 版内核放置
• 首次使用流程
• TUN 模式的权限
• 更新
• 卸载
• 常见安装问题

#版本选择

每个平台都提供 Full 与 Lite 两种安装包，Windows 与 Linux 另有 便携版：

%%{init: {'themeVariables': {'fontSize': '10px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '10px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 15, 'rankSpacing': 25}}}%%
graph LR
    A{需要免安装 /<br/>放在 U 盘?} -->|是| P[便携版<br/>Windows .zip / Linux .tar.gz<br/>内置内核]
    A -->|否| B{已有 Mihomo 内核<br/>或想自行管理内核?}
    B -->|否| C[Full 版<br/>内置内核与 Geo 数据<br/>开箱即用]
    B -->|是| D[Lite 版<br/>不含内核<br/>体积更小]

    C --> E{选择平台与架构}
    D --> E
    E -->|Windows| F[setup .exe 或 .msi<br/>x64 / arm64]
    E -->|macOS| G[.dmg<br/>aarch64 = Apple Silicon<br/>x64 = Intel]
    E -->|Linux| H[.deb / .rpm / .AppImage<br/>amd64 / arm64]

#版本对比

安装包体积参考（以实际 Release 为准）：Windows 安装器 Full 约 25 MB、Lite 约 9 MB；macOS DMG Full 约 40 MB、Lite 约 13 MB；Linux AppImage 因打包了 WebKitGTK 运行库，约 90–110 MB。

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

#系统要求

#运行时依赖

#下载与校验

所有安装包均发布在 GitHub Releases。

#校验签名

• Minisign：每个文件都附带同名 .minisig 签名文件，可用 minisign 校验：

  bash复制

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

• Windows Authenticode：Windows 安装器、MSI 与便携版中的 Zephyr.exe 由 SignPath Foundation 证书签名，可在 PowerShell 中检查：

  powershell复制

  Get-AuthenticodeSignature .\Zephyr_*.exe, .\Zephyr_*.msi

  状态应为 Valid，签名者为 SignPath Foundation。详见仓库 CODE_SIGNING_POLICY.md。

• SBOM：每个 Release 附带 CycloneDX 格式的软件物料清单 v<版本>.cdx.json。

#Windows 安装

#方式一：NSIS 安装器（推荐）

1. 下载 Zephyr_<版本>_x64-setup-full.exe（ARM64 设备选 arm64，需要 Lite 版选 -setup-lite.exe）
2. 双击运行。安装器界面按系统语言显示简体中文或英文
3. 默认为当前用户安装到 %LOCALAPPDATA%\Zephyr，不需要管理员权限；可在目录页修改安装位置
4. 完成页可勾选"创建桌面快捷方式"，并直接启动 Zephyr；开始菜单快捷方式会自动创建

#方式二：MSI 安装包

1. 下载 Zephyr_<版本>_x64_zh-CN-full.msi（或 -lite.msi、arm64 版本）
2. 双击运行，按中文安装向导完成安装

MSI 适合需要通过组策略、Intune 等工具批量部署的场景。

#方式三：包管理器

# Winget
winget install Juwan.Zephyr

# Scoop（安装的是便携版，数据保存在 Scoop 的 persist 目录）
scoop bucket add zephyr https://github.com/Juwan-Hwang/scoop-bucket
scoop install zephyr

包管理器中的版本在 GitHub Release 发布后由工作流自动更新，可能略有延迟。

#macOS 安装

#DMG 安装

1. 前往 GitHub Releases 下载：

   • Apple Silicon（M 系列芯片）：Zephyr_<版本>_aarch64-full.dmg
   • Intel：Zephyr_<版本>_x64-full.dmg

2. 打开 DMG，将 Zephyr 拖入 Applications 文件夹

3. Zephyr 的 macOS 版本未经 Apple 开发者证书签名和公证，首次打开可能提示"已损坏"或"无法验证开发者"。执行：

   bash复制

   xattr -cr /Applications/Zephyr.app

   或在"系统设置 → 隐私与安全性"中点击"仍要打开"。

Zephyr 目前未发布到 Homebrew。

#Linux 安装

#Ubuntu / Debian（.deb）

# 以 x64 Full 版为例；ARM64 将 amd64 换为 arm64
wget https://github.com/Juwan-Hwang/Zephyr/releases/download/v2.5.0/Zephyr_2.5.0_amd64-full.deb
sudo apt install ./Zephyr_2.5.0_amd64-full.deb

#Fedora / RHEL / openSUSE（.rpm）

# 以 x64 Full 版为例；ARM64 将 x86_64 换为 aarch64
wget https://github.com/Juwan-Hwang/Zephyr/releases/download/v2.5.0/Zephyr-2.5.0-1.x86_64-full.rpm
sudo dnf install ./Zephyr-2.5.0-1.x86_64-full.rpm

#Arch Linux（AUR）

yay -S zephyr-clash-bin
# 或
paru -S zephyr-clash-bin

AUR 包 zephyr-clash-bin 基于 x64 Full 版 .deb 重新打包，仅支持 x86_64，在每次 Release 发布后自动更新。

#AppImage（通用）

wget https://github.com/Juwan-Hwang/Zephyr/releases/download/v2.5.0/Zephyr_2.5.0_amd64-full.AppImage
chmod +x Zephyr_2.5.0_amd64-full.AppImage
./Zephyr_2.5.0_amd64-full.AppImage

AppImage 内含 WebKitGTK 运行库，并已修补其辅助进程路径，可在不同发行版上运行；GPU/Mesa 驱动库不打包，使用宿主系统自带的版本。

#便携版

便携版无需安装，所有数据（设置、订阅、内核、Prism 数据）存放在程序所在目录，不写入系统用户数据目录。便携版内置内核与 Geo 数据，相当于 Full 版。

#Windows 便携版

1. 下载 Zephyr_x64-portable.zip 或 Zephyr_arm64-portable.zip
2. 解压到任意目录（如 U 盘、桌面）
3. 运行 Zephyr.exe

#Linux 便携版

mkdir Zephyr && tar xzf Zephyr-linux-x64-portable.tar.gz -C Zephyr
cd Zephyr
chmod +x Zephyr.AppImage
./Zephyr.AppImage

#目录结构

压缩包解压后即包含 .portable 标记文件和数据目录：

Zephyr/
├── Zephyr.exe / Zephyr.AppImage
├── .portable                 ← 便携模式标记（压缩包已自带，必须保留）
├── THIRD-PARTY-LICENSES.txt  ← 第三方许可证
├── core/                     ← mihomo 内核（zephyr-mihomo）和 Geo 数据
├── profiles/                 ← 订阅配置文件
├── prism/                    ← Prism 规则与插件数据
└── settings.json             ← 应用设置（首次运行后生成）

便携模式的判定方式：程序目录（Linux 下为 .AppImage 文件所在目录）存在 .portable 文件。删除该文件后，程序会回到安装版行为，把数据写入系统目录。

#便携版限制

• ❌ 不支持开机自启（设置中隐藏该选项）
• ❌ 不支持客户端内更新（设置中隐藏"自动检查应用更新"，更新对话框会引导到发布页手动下载）
• ✅ 可以在客户端内更新 Mihomo 内核
• ✅ 支持系统代理与 TUN 模式
• 系统 WebView 自身的缓存仍由 Tauri 按默认方式写入当前用户的本地数据目录

#从安装版迁移到便携版

1. 下载便携版并解压
2. 从安装版数据目录复制 profiles/、prism/、settings.json 到便携版目录（数据目录位置见卸载一节）
3. 确认 .portable 文件存在后运行

若开启了"加密配置文件"，配置以本机密钥加密，只能在同一台电脑上使用。

更多说明见仓库 PORTABLE.md。

#Lite 版内核放置

Lite 版不含内核，需要手动放置一次，之后即可在客户端内更新内核。

1. 从 MetaCubeX/mihomo Releases 下载与你系统和架构对应的内核（x64 推荐 amd64-compatible 版本）
2. 解压后将内核重命名为 zephyr-mihomo（Windows 为 zephyr-mihomo.exe）
3. 放入应用数据目录下的 core/ 文件夹：

4. 重新启动 Zephyr。macOS / Linux 下应用会在启动内核前自动补上可执行权限

说明：

• 为兼容旧版本，core/ 下名为 mihomo / mihomo.exe 的内核也能被识别。
• Geo 数据（geoip.dat、geosite.dat、Country.mmdb）同样放在 core/ 中；也可以在"系统设置 → 订阅与规则"中在线更新 Geo 数据。
• 如果 Zephyr 尚未运行过，com.zephyr.desktop 目录可能还不存在，手动创建即可。

#首次使用流程

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A[启动 Zephyr] --> B{Full 版 / 便携版?}
    B -->|是| C[内置内核与 Geo 数据<br/>已就绪]
    B -->|Lite 版| C2[按上文放置内核]
    C2 --> C
    C --> D[订阅管理 → 添加订阅<br/>URL、本地文件或 clash:// 链接]
    D --> E[代理节点页选择节点]
    E --> F[首页开启「系统代理控制」<br/>默认端口 7890]
    F --> G{需要接管所有流量?}
    G -->|是| H[首页开启 TUN 模式<br/>按提示授权]
    G -->|否| I[开始使用]
    H --> J{Windows 商店应用<br/>需要走代理?}
    I --> J
    J -->|是| K[系统设置 → 网络<br/>UWP 环回免除]
    J -->|否| L[配置完成]
    K --> L

#详细步骤

1. 启动应用：从开始菜单、启动台或桌面快捷方式启动。未添加订阅时，内核以仅含 DIRECT 的最小配置运行，首页提示添加订阅。
2. 添加订阅：进入"订阅管理"，点击"添加订阅"，输入订阅 URL 或导入本地文件；也可以点击网页上的 clash:// 链接直接导入。
3. 选择节点：在"代理节点"页浏览节点，可先测试延迟再选择。
4. 开启系统代理：在首页打开"系统代理控制"开关。默认混合端口为 127.0.0.1:7890（订阅配置或设置中指定的端口优先）。
5. （可选）开启 TUN 模式：在首页打开 TUN 开关，用于接管不读取系统代理设置的程序（游戏、命令行工具等）。各平台的授权方式见下一节。
6. （可选，仅 Windows）UWP 环回免除：在"系统设置 → 网络"中点击"免除全部 UWP"，让 Microsoft Store 应用可以访问本地代理。

其他默认行为：关闭窗口时默认最小化到系统托盘；可在"系统设置 → 通用"中开启开机自启动、静默启动、轻量模式等。

#TUN 模式的权限

TUN 需要创建虚拟网卡并修改路由，因此需要提升权限。Zephyr 不安装常驻后台服务，各平台的处理方式如下：

Linux 下的能力授权绑定在内核文件上。内核文件被替换（例如更新内核）后授权随之失效，再次开启 TUN 失败时按提示重新授权即可。

#更新

#客户端（Zephyr 本体）

• 检查方式：在"系统设置 → 关于"中点击"检查更新"，对话框同时显示客户端与内核的可用更新、版本号和发布说明。
• 启动时自动检查：在"系统设置 → 关于"中开启"自动检查应用更新"（默认关闭），启动约 5 秒后检查，有新版本时弹出通知。
• 安装过程：Zephyr 从 GitHub 最新 Release 下载本平台的安装包（Windows .exe/.msi、macOS .dmg、Linux .AppImage/.deb），依次校验 GitHub 提供的 SHA256 摘要和 Minisign 签名，任一失败都会删除下载文件并中止；校验通过后用系统默认程序打开安装包，由你完成安装。
• 便携版不能自我更新，请从发布页下载新版本后替换程序文件（保留数据目录和 .portable）。
• 包管理器安装的用户也可以直接使用 winget upgrade Juwan.Zephyr、scoop update zephyr、yay -Syu 等方式更新。

#Mihomo 内核与 Geo 数据

• 内核更新同样在"检查更新"对话框中进行（可在"系统设置 → 关于"开启"自动检查内核更新"）。内核仅从 MetaCubeX/mihomo 官方 Release 下载并校验 SHA256；替换前备份旧内核，新内核启动失败时自动回滚。
• 同时有客户端和内核更新时，先更新内核再安装客户端。安装新版客户端不会覆盖数据目录中已有的内核，内核始终通过客户端内更新。
• Geo 数据可在"系统设置 → 订阅与规则"中在线更新，同样校验 SHA256。

#卸载

#卸载程序

#彻底清理数据

除 NSIS 卸载时勾选"删除应用数据"外，卸载不会删除配置和日志。如需彻底清理，手动删除：

建议卸载前先在应用内关闭系统代理和 TUN。若卸载后系统代理仍指向 127.0.0.1:7890 导致无法上网，请在系统网络设置中手动关闭代理。

#常见安装问题

#Q: Windows 提示"缺少 WebView2 Runtime"或程序无法启动

A: NSIS 安装器会自动下载 WebView2；使用 MSI 或便携版时需要系统已安装。访问 WebView2 下载页面，下载并安装 "Evergreen Standalone Installer" 后重试。

#Q: Windows SmartScreen 提示"已保护你的电脑"

A: 正式发布的 Windows 安装器已由 SignPath Foundation 证书签名。新证书或新版本在积累足够信誉前仍可能触发 SmartScreen，确认签名有效（见校验签名）后点击"更多信息" → "仍要运行"。

#Q: macOS 提示"已损坏，无法打开"或"无法验证开发者"

A: macOS 版本未经 Apple 签名和公证。执行 xattr -cr /Applications/Zephyr.app，或在"系统设置 → 隐私与安全性"中点击"仍要打开"。

#Q: 下载了错误架构的安装包

A: Windows ARM64 设备选择文件名含 arm64 的包；Apple Silicon Mac 选择 aarch64 的 DMG，Intel Mac 选择 x64；Linux ARM64 选择 arm64（deb）或 aarch64（rpm / AppImage）。

#Q: Linux 启动时提示缺少共享库（.so）或 AppImage 无法运行

A:

• deb / rpm 请使用 apt install ./文件.deb、dnf install ./文件.rpm 安装，以便自动安装依赖。
• AppImage 需要 FUSE 支持（如 Ubuntu 22.04+ 安装 libfuse2），并确认文件有执行权限。
• 如提示 glibc 版本过低，说明发行版早于构建环境（Ubuntu 22.04），请升级系统。
• 诊断缺失的库：ldd /usr/bin/Zephyr | grep "not found"。

#Q: Lite 版启动后内核无法运行

A: 检查内核是否已按Lite 版内核放置放到数据目录的 core/ 下，文件名是否为 zephyr-mihomo(.exe)，架构是否与系统一致。也可以改用 Full 版。

#Q: Windows 开启 TUN 时提示需要管理员权限

A: 选择"以管理员身份重新启动"并在 UAC 中确认即可。若提示"当前 Windows 账户不是管理员"，说明使用的是标准用户账户，无法以本人身份提权，TUN 不可用，可改用系统代理模式。

#Q: 便携版数据仍写入系统目录

A: 确认 .portable 文件与 Zephyr.exe（或 Zephyr.AppImage）位于同一目录；Linux 下还要确认是直接运行该 AppImage 文件。

#Q: 安装后无法连接网络

A: 请检查：

1. 已添加订阅并成功更新节点列表
2. 已选择可用节点（可先测试延迟）
3. 首页系统代理或 TUN 已开启
4. 防火墙未阻止 Zephyr 或 zephyr-mihomo
5. 端口 7890 / 9090 未被其他程序占用

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