本文档以中文撰写。

配置说明

本页描述 Zephyr v2.5.0 的配置体系:设置页面结构、settings.json 字段、数据目录、订阅下载、运行时注入、系统代理、托盘与热重载等。内容以当前代码行为为准。


目录


设置页面结构

设置页分为 7 个分区,右侧边栏提供分区导航,标题旁有搜索框可按关键字定位设置项。另有独立的 高级配置 页面。

graph LR
    S[设置] --> A[外观]
    S --> G[通用]
    S --> P[代理]
    S --> N[网络]
    S --> R[订阅与规则]
    S --> D[数据与安全]
    S --> AB[关于]
    S -.-> ADV[高级配置页]

    A --> A1[语言]
    A --> A2[主题模式 浅色/深色/自动]
    A --> A3[主题颜色]
    A --> A4[应用不透明度]
    A --> A5[界面缩放]
    A --> A6[首页模式 极简/控制台]

    G --> G1[开机自启]
    G --> G2[静默启动]
    G --> G3[关闭到托盘]
    G --> G4[轻量模式]
    G --> G5[全局快捷键]

    P --> P1[智能代理 / 自动测试]
    P --> P2[故障自动切换节点及参数]
    P --> P3[隐藏超时节点]
    P --> P4[统一延迟]

    N --> N1[端口设置]
    N --> N2[复制代理环境变量]
    N --> N3[DNS 覆写与服务器]
    N --> N4[端口转发]
    N --> N5[网络优化]
    N --> N6[UWP 环回免除 Windows]
    N --> N7[局域网连接]

    R --> R1[订阅客户端伪装]
    R --> R2[规则库 自动应用/管理文件]
    R --> R3[Geo 数据更新]

    D --> D1[配置文件加密]
    D --> D2[配置文件夹]
    D --> D3[备份导入/导出]
    D --> D4[日志设置与导出]

    AB --> AB1[应用版本 / 自动检查应用更新]
    AB --> AB2[内核版本 / 检查更新 / 自动检查]
    AB --> AB3[GitHub 主页 / 第三方许可]
    AB --> AB4[恢复默认]

    ADV --> ADV1[自定义启动参数]
    ADV --> ADV2[内核配置]
分区 主要内容
外观 语言、主题模式、主题颜色、不透明度、界面缩放、首页模式
通用 开机自启、静默启动、关闭到托盘、轻量模式、全局快捷键
代理 智能代理、故障自动切换、隐藏超时节点、统一延迟
网络 端口设置、复制环境变量、DNS 覆写、端口转发、网络优化、UWP 环回免除(仅 Windows)、局域网连接
订阅与规则 订阅客户端伪装、规则库、Geo 数据更新
数据与安全 配置加密、打开配置文件夹、备份导入/导出、日志设置与导出
关于 应用/内核版本与更新检查、GitHub 主页、第三方许可、恢复默认
高级配置(独立页面) 自定义启动参数、内核配置(运行配置的可视化编辑)

设置页中不再提供 TUN 开关行;TUN 通过主界面切换。


settings.json 字段

settings.json 位于数据目录根部。字段缺失时取默认值;Option 类字段为 null 表示“未设置”,含义见下表。

全新安装默认值

全新安装时:close_to_tray = true、ui_scale = 1.0、log_retention_days = 3、log_max_file_mb = 50、copy_env_format 在 Windows 为 powershell、其他平台为 bash、schema_version = 1;其余布尔字段为 false,Option 字段为 null,列表/映射为空。

字段表

字段 类型 默认 说明
close_to_tray bool true 关闭窗口时最小化到托盘而非退出
auto_update bool false 启动 5 秒后检查内核更新,仅通知,不自动安装
auto_update_client bool false 启动 5 秒后检查应用更新,仅通知,不自动安装
autostart bool false 开机自启
theme string? null → blue 主题颜色:预设名或自定义十六进制色值
last_config string? null 当前激活的配置文件名 ※
custom_args string[] [] 自定义内核启动参数,每行一个参数
dns_nameservers string[]? null → 内置 DNS 覆写主服务器(见 DNS 防泄漏覆写)
dns_fallbacks string[]? null → 内置 DNS 覆写备用服务器
auto_apply bool false 保留字段;规则库“自动应用”开关实际读写 prism/settings.json
ui_scale number 1.0 界面缩放:1.0 / 1.1 / 1.25 / 1.5
config_order string[] [] 配置文件(订阅)列表的排序
last_proxy_selection map<string,string> {} 每个配置文件最后选择的节点,值为 JSON 字符串 {"group":"…","node":"…"} ※
primary_group_preference map<string,string> {} 每个配置文件偏好的主策略组 ※
subscription_user_agent string? null 订阅下载使用的 UA,由“订阅客户端伪装”同步写入 ※
hide_timeout_nodes bool false 在节点列表中隐藏超时节点
mode string? null → 跟随配置 代理模式 rule / global / direct ※
tun_enabled bool? null → 跟随配置 TUN 开关 ※
mixed_port u16? null → 跟随配置 混合端口(HTTP+SOCKS)
socks_port u16? null → 跟随配置 SOCKS 端口
http_port u16? null 预留字段,目前界面不单独设置 HTTP 端口
ipv6 bool? null → 跟随配置 IPv6
allow_lan bool? null → 跟随配置 允许局域网连接
unified_delay bool? null 统一延迟(mihomo unified-delay)
dns_rewrite_enabled bool? null → 开启 DNS 覆写开关
theme_mode string? null → auto light / dark / auto
app_opacity u8? null → 100 窗口不透明度,界面范围 10–100
node_scroll bool? null 保留字段,界面已无对应设置
failover_enabled bool false 节点连续失败时自动切换
network_optim_auto_apply bool false 启动时自动应用网络优化
lightweight_mode bool false 轻量模式:与 close_to_tray 同时开启时,关闭窗口即销毁 WebView 释放内存,点击托盘重建;close_to_tray 关闭时无效
silent_start bool false 静默启动:启动时不显示主窗口,仅显示托盘图标
encrypt_configs bool false 加密配置文件;切换时立即加密/解密现有文件 ※
log_app_enabled bool false 将应用事件写入磁盘日志
log_core_enabled bool false 将内核 stdout/stderr 写入磁盘日志
log_retention_days u32 3 日志保留天数,界面范围 1–30
log_max_file_mb u32 50 单个日志文件上限(MB),界面范围 1–500
copy_env_format string Windows powershell,其他 bash 复制环境变量的格式:bash / fish / cmd / powershell / nushell
home_page_mode string? null → minimal 首页模式:minimal(极简)/ console(控制台)
schema_version u32 1(缺失视为 0) 设置结构版本,用于自动迁移

仅由专用命令修改的字段(※)

以下字段只由各自的专用命令写入。前端整体保存设置(save_settings)时,后端会保留自己持有的副本,不会被覆盖:

mode、tun_enabled、encrypt_configs、last_config、last_proxy_selection、primary_group_preference、subscription_user_agent

此外,局部更新命令 patch_settings 拒绝为 mode 或 tun_enabled 写入非 null 值;传 null 表示重置为“跟随配置”。设置变更总是先持久化再广播。

损坏与迁移

场景 行为
settings.json 无法解析 原文件重命名为 settings.corrupt.<毫秒时间戳>.json,然后写入默认设置
schema_version 低于当前版本 依次执行迁移;v0 → v1 将 last_proxy_selection 中旧的纯节点名字符串转换为 {"group","node"} JSON
写入 原子写入(先写临时文件再替换),文件权限仅限当前用户

示例:

json
{
  "close_to_tray": true,
  "auto_update": false,
  "auto_update_client": false,
  "autostart": false,
  "theme": "blue",
  "theme_mode": "auto",
  "ui_scale": 1.0,
  "mode": null,
  "tun_enabled": null,
  "mixed_port": 7890,
  "dns_rewrite_enabled": true,
  "last_proxy_selection": {
    "my-sub.yaml": "{\"group\":\"Proxy\",\"node\":\"HK-01\"}"
  },
  "log_retention_days": 3,
  "log_max_file_mb": 50,
  "copy_env_format": "bash",
  "home_page_mode": "minimal",
  "schema_version": 1
}

数据存储目录

应用标识为 com.zephyr.desktop。

平台 路径
Windows %APPDATA%\com.zephyr.desktop
macOS ~/Library/Application Support/com.zephyr.desktop
Linux ~/.local/share/com.zephyr.desktop(Tauri 默认数据目录)
便携模式 可执行文件(或 AppImage)同目录存在 .portable 文件时,数据存放在该目录下

目录结构

com.zephyr.desktop/
├── settings.json                  # 应用设置
├── core/
│   ├── zephyr-mihomo(.exe)        # 内核可执行文件
│   ├── run_config.yaml            # 运行时配置(由激活配置生成)
│   ├── cache.db
│   ├── geoip.dat
│   └── geosite.dat
├── profiles/
│   ├── *.yaml                     # 配置文件 / 订阅
│   ├── metadata.json              # 订阅元数据
│   └── metadata.json.bak          # 元数据备份
├── logs/
│   ├── app/YYYY-MM-DD.log         # 超出大小上限后为 YYYY-MM-DD-N.log
│   └── core/YYYY-MM-DD.log
├── prism/
│   ├── *.prism.yaml               # 规则文件(停用时为 .disabled 副本)
│   ├── groups.json
│   ├── settings.json              # 规则库设置(含 auto_apply)
│   ├── smart.toml
│   ├── smart_history.wal / .json
│   ├── kv_store.db
│   ├── plugins/
│   └── overrides/
│       ├── meta.json
│       ├── {id}.js 或 {id}.prism.yaml
│       ├── {id}.log.json
│       └── override_{id}.prism.yaml   # 生成文件
├── .sys-proxy-ownership           # 系统代理所有权标记
├── .subscription-global-restore   # 订阅下载临时切 GLOBAL 后的恢复标记
└── tcp-backup.conf                # 网络优化前的 TCP 参数备份

文件说明

文件 说明
profiles/*.yaml 默认明文。开启 encrypt_configs 后以 AES-256-GCM 加密,存储为 "v2:" + nonce + 密文 + tag 的 Base64,因此文件内容以 djI6 开头;加密文件无法在其他机器上使用
profiles/metadata.json 明文 JSON;开启加密时仅 url 与 sub_info 的值被加密,last_updated、auto_update_interval、user_agent 保持明文
.machine_key 仅当无法获取硬件 ID 时作为备用密钥,存放于 %APPDATA%\Zephyr(Windows)、~/Library/Application Support/Zephyr(macOS)或 ~/.config/Zephyr(Linux),从不放在便携目录中

设置页 数据与安全 → 配置文件夹 按钮打开的是 profiles/ 目录。


外观:主题、缩放与语言

主题颜色

名称 色值
蓝色(默认) #007AFF
绿色 #34C759
橙色 #FF9500
粉色 #FF2D55
自定义 任意十六进制色值

zinc 作为取值仍被接受,但没有对应色块。

其他外观项

设置 取值
主题模式 浅色 / 深色 / 自动(跟随系统,默认)
应用不透明度 10–100(默认 100)
界面缩放 100% / 110% / 125% / 150%
语言 14 种界面语言,保存在浏览器 localStorage 的 lang 键中
首页模式 极简(默认)/ 控制台

端口设置

网络 → 端口设置 打开端口对话框。

端口 平台
mixed(混合) 全平台
socks 全平台
redir Linux / macOS
tproxy 仅 Linux

规则:

  • 填 0 表示关闭该端口;
  • mixed 与 socks 至少保留一个开启;
  • 各端口不能重复;
  • 保存时总会附带 port: 0(关闭独立 HTTP 端口)。

端口转发

网络 → 端口转发 管理转发规则,每条规则:

字段 取值 说明
network tcp / udp / tcp+udp 协议
address 例如 127.0.0.1:6000 本地监听地址
target 例如 example.com:22 转发目标

规则不指定代理节点,流量经由当前代理转发。

json
{ "network": "tcp", "address": "127.0.0.1:6000", "target": "example.com:22" }

复制环境变量

网络 → 复制代理环境变量(以及托盘菜单)按 copy_env_format 生成命令:

以端口 7890 为例:

bash
# bash(默认,非 Windows)
export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890 all_proxy=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 ALL_PROXY=http://127.0.0.1:7890
fish
# fish
set -x http_proxy http://127.0.0.1:7890; set -x https_proxy http://127.0.0.1:7890; set -x all_proxy http://127.0.0.1:7890; set -x HTTP_PROXY http://127.0.0.1:7890; set -x HTTPS_PROXY http://127.0.0.1:7890; set -x ALL_PROXY http://127.0.0.1:7890
bat
:: cmd(仅小写,cmd 不区分大小写)
set http_proxy=http://127.0.0.1:7890&set https_proxy=http://127.0.0.1:7890&set all_proxy=http://127.0.0.1:7890
powershell
# powershell(默认,Windows)
$env:http_proxy="http://127.0.0.1:7890"; $env:https_proxy="http://127.0.0.1:7890"; $env:all_proxy="http://127.0.0.1:7890"; $env:HTTP_PROXY="http://127.0.0.1:7890"; $env:HTTPS_PROXY="http://127.0.0.1:7890"; $env:ALL_PROXY="http://127.0.0.1:7890"
nu
# nushell
$env.http_proxy = "http://127.0.0.1:7890"; $env.https_proxy = "http://127.0.0.1:7890"; $env.all_proxy = "http://127.0.0.1:7890"; $env.HTTP_PROXY = "http://127.0.0.1:7890"; $env.HTTPS_PROXY = "http://127.0.0.1:7890"; $env.ALL_PROXY = "http://127.0.0.1:7890"

地址默认使用 http:// 方案;当只开放 SOCKS 端口时使用 socks5h://。


订阅

订阅客户端伪装

位于 订阅与规则,设置保存在 localStorage:

键 默认 说明
fakeClientEnabled 开启 是否伪装客户端 UA
fakeClientType clash-verge/1.6.0 伪装的客户端类型
fakeClientCustom 空 选择“自定义”时的 UA

可选客户端的版本号从各项目 GitHub 最新发布 API 获取。最终 UA 同步写入 settings.json 的 subscription_user_agent,供后台定时更新使用。

订阅选项

项目 行为
自动更新间隔 每个订阅单独设置:关闭(0)/ 12 小时 / 1 天 / 3 天
UA 每个订阅可单独覆盖;未设置时使用全局伪装 UA,再无则为 Zephyr/<版本>;选择 Shadowrocket 时发送完整的 Shadowrocket UA
排序 保存在 config_order
大小上限 10 MB
内容格式 Base64 编码内容会自动解码
文件名 优先取响应头 Content-Disposition,否则按规则生成;与已有文件同名(如 clash)时追加 -N 后缀

三级下载策略

flowchart TD
    A[开始下载订阅] --> B{直连成功?}
    B -- 是 --> Z[保存]
    B -- 否 --> C{经内核 mixed 端口成功?}
    C -- 是 --> Z
    C -- 否 --> D[临时切换到 GLOBAL 模式并写入恢复标记]
    D --> E[下载]
    E --> F[恢复原模式并删除标记]
    F --> Z

若应用在临时 GLOBAL 期间退出,下次启动会根据 .subscription-global-restore 恢复原模式。

参数 值
定时更新总时长预算 14 秒
手动更新总时长预算 25 秒
手动更新限速 每 5 秒 1 次,超出的请求排队
调度器检查周期 每 60 秒

运行时配置处理

启动内核前,激活配置会被处理并写入 core/run_config.yaml。

移除的键

出于安全考虑,以下键会被删除:

键 说明
script、script-path 脚本
cfw-* Clash for Windows 专有键
各 provider 的 path 防止写入任意路径
external-controller-unix、external-controller-pipe、external-controller-tls、external-controller-cors 额外控制接口
external-doh-server 外部 DoH 服务
external-ui* 外部面板

注入的默认值

配置中未设置时才注入:

yaml
unified-delay: true
tcp-concurrent: true
keep-alive-interval: 30
keep-alive-idle: 600
profile:
  store-fake-ip: true
find-process-mode: always

控制接口密钥(secret)每次启动都会重新生成 32 位随机值。

TUN 注入

开启 TUN 时注入:

yaml
tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

Windows:保存的 TUN 偏好仅在应用以管理员权限运行时生效。


DNS 防泄漏覆写

网络 → DNS 覆写 开启时(默认开启),通过内核 API 下发以下补丁。它是运行时叠加层,只作用于正在运行的内核,不会写入配置文件。关闭时下发 dns.enable: false 与 sniffing: false。

yaml
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"
    - localhost.ptlogin2.qq.com
    - "*.msftncsi.com"
    - "*.srv.nintendo.net"
    - "*.stun.playstation.net"
    - xbox.*.microsoft.com
    - "*.xboxlive.com"
    - "*.stun.steamwire.com"
    - stun.*
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
    - 1.1.1.1
    - 8.8.8.8
  nameserver:            # 可在“服务器”中修改,保存为 dns_nameservers
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:              # 可在“服务器”中修改,保存为 dns_fallbacks
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query

自定义服务器支持 DoH(https://)、DoT(tls://)、IPv4 与 IPv6(可带端口)格式。default-nameserver 必须是 IP,用于解析 DoH/DoT 服务器域名。


配置热重载与高级配置页

运行配置更新

需要修改运行配置的设置(例如端口、模式等)走以下流程:

sequenceDiagram
    participant UI as 前端
    participant B as 后端
    participant F as 文件
    participant C as mihomo 内核
    UI->>B: update_config(patch)
    B->>F: 合并 patch 到 core/run_config.yaml
    B->>F: 回写到当前激活的配置文件
    B->>C: PUT /configs?force=true {"path": "…/run_config.yaml"}
    C-->>B: 重载完成
    B-->>UI: 结果

write_config_file 只写入文件本身,不同步 run_config.yaml,也不调用内核 API。

高级配置页

  • 内核配置:编辑后先以 PATCH /configs(不带 force)应用到运行中的内核,再通过 write_config_file 保存到配置文件。
  • 自定义启动参数:见下节。

自定义启动参数

每行作为一个独立参数传给内核。以下参数(包括 --参数=值 形式)被禁止,出现时内核启动失败并提示错误:

禁止参数 原因
-d、--directory 由 Zephyr 管理工作目录
-f、--config 由 Zephyr 管理配置文件
-ext-ctl、--external-controller 由 Zephyr 管理控制接口
-secret、--secret 密钥每次启动自动生成

延迟测试

项目 值
测试地址 https://www.gstatic.com/generate_204
超时 5000 ms
统一延迟 对应 mihomo unified-delay

托盘

状态 图标
系统代理开启 绿色
TUN 开启 红色
空闲 跟随系统主题(macOS 为模板图标)

菜单要点:

  • 复制环境变量:按 copy_env_format 复制,完成或失败分别触发 tray-copy-env-done / tray-copy-env-failed 事件;
  • 代理 子菜单:列出主策略组中最多 15 个节点,全局模式下列出 GLOBAL 组;

系统代理

平台 实现
Windows / macOS 写入系统代理设置
Linux 对检测到的所有桌面环境同时应用:GNOME、KDE、XFCE

所有权标记:开启系统代理时写入 .sys-proxy-ownership。

  • 若系统代理被外部关闭,Zephyr 每 10 秒检查一次并重新开启;
  • 应用崩溃后再次启动时,依据该标记恢复系统代理。

深度链接导入

格式:

clash://install-config?url=<订阅地址>&name=<名称>
约束 说明
url 必须为 http 或 https
长度 链接不超过 2048 字符

链接作为命令行参数传给 Zephyr 时会被处理并导入订阅。是否能从浏览器直接唤起,取决于系统中是否已有程序将 clash:// 关联到 Zephyr;本仓库未包含该协议的系统注册。

↑↓ 选择↵ 打开