Configuration

配置说明

本页描述 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
写入	原子写入（先写临时文件再替换），文件权限仅限当前用户

示例：

{
  "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`	转发目标

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

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

复制环境变量

网络 → 复制代理环境变量（以及托盘菜单）按 copy_env_format 生成命令：

以端口 7890 为例：

# 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
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

:: 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（默认，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"

# 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://。

项目	行为
自动更新间隔	每个订阅单独设置：关闭（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*`	外部面板

注入的默认值

配置中未设置时才注入：

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 时注入：

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。

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；本仓库未包含该协议的系统注册。

导航

外部链接

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

Configuration

配置说明

目录

设置页面结构

settings.json 字段

全新安装默认值

字段表

仅由专用命令修改的字段（※）

损坏与迁移

数据存储目录

目录结构

文件说明

外观：主题、缩放与语言

主题颜色

其他外观项

端口设置

端口转发

复制环境变量

订阅

订阅客户端伪装

订阅选项

三级下载策略

运行时配置处理

移除的键

注入的默认值

TUN 注入

DNS 防泄漏覆写

配置热重载与高级配置页

运行配置更新

高级配置页

自定义启动参数

延迟测试

托盘

系统代理

深度链接导入

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally