mihomo-cli 3.5.0 → 3.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +61 -20
  3. package/dist/index.js +625 -262
  4. package/package.json +5 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,73 @@
1
1
  # Changelog
2
2
 
3
+ ## [3.7.0] - 2026-08-22
4
+
5
+ ### 修复
6
+
7
+ - **错误响应体绕过大小上限，可致 OOM** - `!response.ok` 分支直接 `await response.json()`，不经流式大小检查。实测 60MB 错误体使客户端 RSS 增长 303MB——攻击者只需返回非 2xx 即可绕过 50MB 防护。现错误体限量 64KB 读取（仅用于诊断），修后 RSS 增长 9MB
8
+ - **机场返回错误 JSON 会覆盖磁盘上可用的订阅** - 下载后只要内容能解析成对象就原子覆盖写盘。机场返回 `{"error":"quota exceeded"}` 之类响应时报「已更新 (0 节点)」，把原本可用的订阅**不可恢复地覆盖**，随后 mihomo 带零节点启动导致断网；且这在 `start` 的自动更新路径上，用户无操作即触发。现写盘前要求 `proxies`/`proxy-groups`/`proxy-providers` 至少其一非空，并提取服务端错误信息作为提示
9
+ - **`ps` 输出截断致测速实例泄漏并占用端口** - `isProcessCommandMatching` 未带 `-ww`，BSD/macOS 的 `ps` 即使 stdout 非终端也把 command 列截断到 79 列。测速实例的匹配串（`test/runtime/config.yaml`）起始偏移随用户名增长（`alice` 为 80、`jonathan.smith` 为 98），常见家目录下均越界 → 匹配恒失败 → `stopTestInstance` 跳过 SIGKILL 却仍删 pid 文件，内核残留占着 27890/29090 且再无记录，下次 `sub test` 直接启动失败
10
+ - **`sub add` 失败时劫持当前活跃订阅** - `setDefaultSubscription` 在下载之前执行，回滚时 `removeSubscription` 把活跃订阅落到列表首项而非用户原选择。复现：活跃为 `work`、列表为 `[airport-a, work]`，添加一个不可达 URL 失败后活跃变成 `airport-a`，下次 `start` 静默连错机场。现切换移到下载成功之后
11
+ - **`MIHOMO_CLI_DAEMON_LABEL` 未校验导致 root 任意路径写** - 该值经 `path.join` 拼成 plist 路径后，是 `sudo install -m 644 -o root` 的写入目标与 `sudo rm -f` 的删除目标，而 `path.join` 会折叠 `..`（`../../etc/sudoers.d/evil` → `/etc/sudoers.d/evil.plist`），内容还部分可控。现加字符集校验：非法值回退默认标签，并在 `enableDaemon`/`disableDaemon` 入口报错
12
+ - **覆写注入节点的 `exclude-filter` 误排除同前缀节点** - mihomo 的 `exclude-filter` 是无锚点正则搜索。注入名为 `HK` 的节点后，订阅里的 `HK-01`/`HK-02` 全被踢出 `include-all` 分组。现改为 `^(?:...)$` 整名锚定
13
+ - **覆写 YAML 笔误抛裸 `TypeError` 并打印堆栈** - `validateConfig` 的类型断言无校验，四种常见笔误会崩溃：`proxies` 含空列表项、`rules` 漏写 `-` 成标量、`proxy-groups` 写成映射、`rules` 含非字符串。用户配置错误被当成程序 bug。现全部转为带修正提示的 `CliError`
14
+ - **`~key`/`+key` 作用于非数组时静默损坏配置** - 静默包成单元素数组：`~dns: {enable: true}` 把映射 `dns` 变成 `[{enable: true}]` 并丢掉原有字段，而 mihomo 要求 `dns` 是映射；`log-level+: debug` → `["debug"]` 同理。现报错并提示改用 `key!` 或直接写 `key`；目标不存在时仍放行（新增数组的正常用法）
15
+ - **`maskUrl` 逗号切分致 token 明文泄漏** - 无条件按逗号切分，`?nodes=us,hk&token=SECRET` 被劈开后两段都识别不出 token 参数，密钥明文输出。同一根因还让 query 含逗号的合法单 URL（`?flag=clash,meta`）被误判多源、`sub add` 报「无效的 URL」而无法添加。现统一判据为「切分后每段都是合法 http(s) URL 且不止一段」
16
+ - **`settings.json` 为合法 JSON 但非对象时绕过损坏恢复** - `null`/`[]`/`123`/`"hi"` 都直接进缓存，不备份不告警：`null` 让 `getSubscriptions()` 抛裸 `TypeError` 且缓存判定恒失效，字符串被展开成 `{"0":"h","1":"i",...}`。现一并走备份+回退分支
17
+ - **`subscriptions` 非数组时被按字符展开** - 手改成 `"oops"` 后 `addSubscription` 写出 `["o","o","p","s",{...}]` 且不报错。现在唯一读取入口 `getSubscriptions()` 收口校验，并滤掉缺 name/url 的残缺条目
18
+ - **`reset` 忽略停止进程的结果** - root 实例（TUN）下走 `sudo pkill`，用户取消密码时失败的 pid 被静默丢弃，仍继续删除数据，留下孤儿 root 进程跑在已删配置上。现删数据前复查并中止
19
+ - **`reset --full` 残留含密钥的备份文件** - `settings.json.bak`（损坏恢复时生成）带 `controller_secret` 与订阅 token 明文留下，与「已重置: 设置」矛盾。现纳入删除路径
20
+ - **`reset` 结果依赖参数顺序** - `subs` 目标的后置钩子会重建 `settings.json`，故 `reset settings subs` 留下 `{}` 而 `reset subs settings` 才真删。现按注册表顺序执行
21
+ - **`match` 的订阅名匹配与 `sub use` 口径不一致** - `sub use home` 能切到订阅 `Home`（模糊匹配大小写不敏感），但 `match: {subscription: home}` 精确比对匹配不上。现统一为大小写不敏感
22
+ - **`parseIntArg` 接受危险值** - 无范围校验：`-j 0` 让测速起 0 个 worker、结果全空洞、被报成「所有节点失败」（伪造结果）；`-t 5s` 静默取 5ms 让全部节点超时。现非正整数一律报错，并把 `test`/`clean` 的参数校验移到运行状态检查之前
23
+ - **合并订阅的错误指向被连带取消的 URL** - 任一 URL 失败即中断其余请求，按顺序取第一个错误报出的往往是被取消的那条，真正的 403/token 过期被隐藏。现优先报非取消类错误
24
+ - **`dir` 子命令的错误绕过统一渲染** - `cmdDirectory` 用 `void` 丢弃 async 分发的 Promise，`dir open <未知目标>` 抛的错误退化成「未处理的 Promise 拒绝」，丢掉标签颜色与可用目标列表
25
+ - **`ow`/`dir` 未知子命令静默回落** - `ow onn` 静默打印列表且退出码 0（对比 `sub adz` 会报错并给纠错建议）。现补齐纠错提示
26
+ - **测速实例的 pid 记录时机存在泄漏窗口** - spawn 与写 pid 文件之间被 Ctrl+C 中断时，只认 pid 文件的清理逻辑会漏掉 detached 子进程。现增加内存记录作为第二来源
27
+ - **`reset` 保活取消路径退出码为 0** - `console.error` + `return` 使「重置中止」被脚本误判成功，且绕过统一渲染
28
+ - **`mihomo on`/`off` 丢弃启动选项** - 唯二不透传后续参数的快捷命令，`mihomo on -s` 静默吞掉 `-s`，而 README 声明其与 `ow on` 等价
29
+ - **`restartDaemon` 抛裸 `Error`** - 最后一处未迁移的数据层预期错误
30
+
31
+ ### 新增
32
+
33
+ - **平台守卫** - `package.json` 声明 `"os": ["darwin"]`，`main()` 开头校验平台（豁免 `help`/`version`，`MIHOMO_CLI_ALLOW_ANY_PLATFORM=1` 为开发逃生阀）。此前非 macOS 上是「部分成功」：`status`/`sub` 看着正常，`daemon on` 输完 root 密码才撞 `/Library/LaunchDaemons`，`ui` 报告成功却什么都没打开（`open` 命令缺失被吞掉，且 Debian 的 `open` 指向 `run-mailcap` 会把 URL 当附件处理）。守卫先于目录创建，避免在不支持的平台留下数据目录
34
+ - **`sub remove` 模糊匹配需确认** - 精确名称直接删除；模糊命中时展示完整名称并要求确认（`-y`/`--yes` 跳过）。此前 `sub remove air` 会无提示删掉 `production-airport`
35
+ - **`subs` 别名** - 与 `directory` 的 `dirs` 对称，落地命名规范的「简写复数」档
36
+ - **GitHub Actions CI** - 在 `macos-latest` 上跑 typecheck / lint / test / build
37
+ - **`prepublishOnly` 钩子** - `dist/` 被 gitignore 且此前无发布钩子，漏跑构建即发布陈旧或缺失产物
38
+
39
+ ### 变更
40
+
41
+ - **破坏性操作在非交互环境报错而非静默取消** - `reset`（无 `-y`）与 `sub remove`（模糊匹配）在管道/CI 下此前打印「已取消」并退出 0，脚本会误判操作已完成。现报错退出 1 并提示加 `-y` 或用完整名称
42
+ - **`confirmPrompt` 收敛到 `commands/shared.ts`** 并增加 TTY 守卫（此前在非交互环境会挂住等输入）
43
+
44
+ ### 内部
45
+
46
+ - **单测从 55 增至 101** - 新增覆盖：配置形态校验、`exclude-filter` 锚定、覆写数组语义误用、`match` 大小写、`parseIntArg` 边界、多源 URL 逗号判据
47
+ - **`CODE_REVIEW.md` 重写** - 上一轮（v2.9.x 基线）的「仍待处理」清单已逐项复核：#12/#14 实际已修复，#10 的后果比原描述严重（是 token 泄漏而非仅显示切碎），#17 的建议不可行——上游 v1.19.30 的 127 个资产中零 checksum 文件，故真实缺口是下载地址的 host 未钉死。新增 9 项待处理（tar symlink 致任意文件 chmod 755、热重载信任任意 9090 响应、`Subscription-Userinfo` 边界等）
48
+ - **`README.md` / `CLAUDE.md` 校正** - 平台说明从「Windows / Linux 正在适配中」改为「仅支持 macOS」（此前无对应代码）；覆写实为默认启用（此前文档教用户先 `ow on`）；`log -o` 是系统默认程序而非编辑器；补齐 `logs current`、长选项、`reset`/`dir open` 完整目标列表、分阶段调试文件；新增「选项写法」「数据保护」两节
49
+
50
+ ## [3.6.0] - 2026-08-15
51
+
52
+ ### 修复
53
+
54
+ - **`sub add` 重名时误删既有同名订阅** - 回滚逻辑包住了入库步骤，添加重名订阅时「已存在」错误同样触发 `removeSubscription`，把用户既有的同名订阅（含缓存与配置文件）删掉。现入库移出 try 块，回滚仅覆盖「入库成功后下载失败」
55
+ - **`start` 拼错模式名静默按 Mixed 启动** - `mihomo start tn` 之类只判 `=== 'tun'`，拼错不报错，用户会误以为已切到 TUN。现校验模式参数并报错，参数校验先于内核/订阅环境检查
56
+ - **pidFile 运行判定可被 PID 复用欺骗** - 只检查 pid 存活，系统重启后残留 pid 文件里的 pid 可能已被无关进程复用，被误判成运行中的 mihomo。现同时校验进程命令行包含内核路径（与测速实例防护同口径）
57
+ - **数据层预期错误打印堆栈** - 订阅名称非法/重名、未找到订阅配置、无有效节点、内核/配置缺失等用户可见的预期错误仍抛裸 `Error`，经统一收口后打印堆栈。现全部迁移为 `CliError`
58
+
59
+ ### 新增
60
+
61
+ - **did-you-mean 纠错** - 未知命令与 `sub`/`daemon` 未知子命令按前缀 + 编辑距离给出纠错建议（如 `mihomo strt` -> `是否想输入: start / stop?`）
62
+ - **`update` 更新前检查最新版** - 先查 npm registry，已是最新版本则跳过重装；查询失败（15s 超时）降级为直接安装
63
+ - **`status` 显示订阅流量与到期** - 复用订阅缓存的响应头数据，有则展示
64
+ - **场景化提醒** - `ui` 在 mihomo 未运行时提示先启动；`kernel` 更新成功后运行中实例提示需重启生效
65
+
66
+ ### 内部
67
+
68
+ - **utils 按职责拆分** - `colors.ts`（颜色）、`errors.ts`（CliError/TimeoutError/withTimeout）、`http.ts`（HTTP 客户端）独立成模块；`isProcess*` 进程探测归入 `process.ts`，`isProxyValid` 归入其唯一消费者 `test-instance.ts`；`VERSION`/`PKG_NAME` 移入 `constants.ts`。`utils.ts` 只留无副作用的纯函数（sleep、转义、格式化、flag 解析、纠错建议）
69
+ - **补充单元测试** - 新增 `suggestSimilar`（did-you-mean）单测，总计 55 个
70
+
3
71
  ## [3.5.0] - 2026-08-15
4
72
 
5
73
  ### 变更
package/README.md CHANGED
@@ -1,22 +1,25 @@
1
1
  # mihomo-cli
2
2
 
3
- 一个基于命令行的 mihomo (Clash.Meta) 客户端，专为 macOS 设计。Windows / Linux 正在适配中，敬请期待。
3
+ 一个基于命令行的 mihomo (Clash.Meta) 客户端，**仅支持 macOS**。
4
+
5
+ 进程保活依赖 launchd、目录/UI 打开依赖 `open`、提权依赖 `sudo`，均无其他平台实现，故在非 macOS 上会直接报错退出而非部分可用。Windows / Linux 适配尚无时间表。
4
6
 
5
7
  ## 功能特性
6
8
 
7
9
  - 🌐 **订阅管理** - 添加/更新订阅，支持流量统计和到期时间显示
8
10
  - 🔄 **自动更新** - 启动时自动检查并更新过期订阅
9
- - 🔍 **模糊匹配** - `sub use` / `sub web` 支持订阅名称模糊匹配
11
+ - 🔍 **模糊匹配** - `sub use` / `web` / `update` / `remove` / `test` / `clean` 均支持订阅名称模糊匹配（大小写不敏感）
10
12
  - 🧹 **节点测速清理** - `test` 快速测试、`clean` 清理并重启；`sub test/clean` 独立进程测试任意订阅
11
13
  - 📝 **覆写配置** - 在订阅基础上进行自定义覆写，支持强制覆盖、数组合并、按 name 就地 patch、按订阅限定作用域
12
14
  - 🔄 **智能重启** - `sub use` 切换订阅、`ow on/off` 切换覆写后自动重启
13
15
  - 🚀 **进程管理** - 启动/停止/切换模式，自动清理残留进程
14
16
  - 🛡️ **进程保活** - 基于 launchd（root），崩溃/开机自动拉起，代理后台常驻（`daemon on`）
15
17
  - 🔄 **双模式支持** - Mixed 模式和 TUN 透明代理模式
16
- - 📊 **状态监控** - 查看运行状态、内存占用
18
+ - 📊 **状态监控** - 查看运行状态、内存占用、订阅流量与到期时间
17
19
  - 📝 **日志管理** - 实时日志 + 历史日志归档（自动轮转，保留7天）
18
20
  - 🎨 **Web UI** - 一键打开 Web 控制面板 (zash/metacubexd/yacd)
19
21
  - 🔄 **内核更新** - 自动检查更新，支持 GitHub 镜像加速
22
+ - 💡 **容错提示** - 命令/子命令拼错时给出 did-you-mean 纠错建议
20
23
  - ⌨️ **命令别名** - `mihomo` / `mhm` / `mh` 均可调用
21
24
 
22
25
  ## 安装
@@ -86,9 +89,11 @@ mihomo ui yacd # YACD
86
89
  | --------------------------- | ---------------------------------------------------------------------------- |
87
90
  | `mihomo start [tun\|mixed]` | 启动/重启/切换代理模式（`-s` 跳过更新，`-u` 更新超时，`-r` 清理轮次，`-t` 超时，`-j` 并发，`--no-clean` 跳过启动自动清理） |
88
91
  | `mihomo stop` | 停止代理 |
89
- | `mihomo status` | 查看运行状态 |
90
- | `mihomo log` | 实时查看日志 (`-o` 用系统编辑器打开) |
92
+ | `mihomo status` | 查看运行状态（含订阅流量、到期时间） |
93
+ | `mihomo log` | 实时查看日志 (`-o` 用系统默认程序打开) |
91
94
  | `mihomo logs` | 列出所有日志（当前 + 历史归档） |
95
+ | `mihomo logs current` | 查看当前日志（等同 `logs 0`） |
96
+ | `mihomo logs <名称/子串>` | 按文件名或子串查看指定归档日志 |
92
97
  | `mihomo logs <编号>` | 查看指定日志（`0`=当前日志，`1+`=归档日志，支持 `-n N` 指定行数、`-o` 打开） |
93
98
 
94
99
  ### 订阅管理
@@ -100,10 +105,10 @@ mihomo ui yacd # YACD
100
105
  | `mihomo sub add <url> [name]` | 添加订阅并自动切换（支持逗号分隔多 URL 合并，名称不可重复） |
101
106
  | `mihomo sub update` | 更新所有订阅 |
102
107
  | `mihomo sub update <name>` | 更新指定订阅（支持模糊匹配） |
103
- | `mihomo sub remove <name>` | 删除订阅（支持模糊匹配） |
104
- | `mihomo sub web [name]` | 打开订阅页面（无参打开默认） |
108
+ | `mihomo sub remove <name>` | 删除订阅（别名 `rm`/`delete`；精确名直接删，模糊匹配需确认，`-y` 跳过） |
109
+ | `mihomo sub web [name]` | 打开订阅页面（别名 `open`，无参打开默认，支持模糊匹配） |
105
110
  | `mihomo sub test [name]` | 测试节点连通性（独立隔离实例，无需运行主实例，`-t` 超时，`-j` 并发） |
106
- | `mihomo sub clean [name]` | 测速并清理失败节点（独立实例，不动主实例，`-r` 轮数，默认2）|
111
+ | `mihomo sub clean [name]` | 测速并清理失败节点（独立实例，不动主实例，`-r` 轮数默认 2，`-t` 超时，`-j` 并发） |
107
112
  | `mihomo test` | 测试当前节点（经运行中的主实例，`-t` 超时，`-j` 并发） |
108
113
  | `mihomo clean` | 清理失败节点并重启（经主实例，`-t` 超时，`-j` 并发，`-r` 轮数） |
109
114
 
@@ -111,21 +116,21 @@ mihomo ui yacd # YACD
111
116
 
112
117
  | 命令 | 说明 |
113
118
  | ------------------------------ | -------------------------- |
114
- | `mihomo ow` / `mihomo ow list` | 查看覆写配置状态和文件列表 |
115
- | `mihomo ow on` | 启用覆写配置（自动重启） |
116
- | `mihomo ow off` | 禁用覆写配置（自动重启） |
119
+ | `mihomo ow` / `mihomo ow list` | 查看覆写配置状态和文件列表（别名 `enable`/`disable` 亦可用于开关） |
120
+ | `mihomo ow on` | 启用覆写配置（**默认已启用**，自动重启） |
121
+ | `mihomo ow off` | 禁用覆写配置（自动重启） |
117
122
 
118
123
  ### 其他命令
119
124
 
120
125
  | 命令 | 说明 |
121
126
  | --------------------------------- | ------------------------------------------------------------------- |
122
- | `mihomo kernel [--mirror [镜像]]` | 更新内核（默认直连，`--mirror` 使用镜像） |
127
+ | `mihomo kernel [--mirror [镜像]]` | 更新内核（默认直连，`--mirror` 使用镜像；更新后运行中实例需重启生效） |
123
128
  | `mihomo daemon [on\|off\|status]` | 进程保活：开机自启 + 崩溃自动重启（仅 Mixed 模式，on/off 需管理员密码） |
124
- | `mihomo update` | 更新 mihomo-cli (npm install -g) |
129
+ | `mihomo update` | 更新 mihomo-cli（先查 npm 最新版，已是最新则跳过重装） |
125
130
  | `mihomo ui [zash\|dash\|yacd]` | 打开 Web UI |
126
131
  | `mihomo dir` | 显示数据目录位置 |
127
- | `mihomo dir open [target]` | 打开指定目录（`root`, `subs`, `logs`, `kernel` 等） |
128
- | `mihomo reset [目标...] [--full] [-y]` | 重置用户数据（可用目标：`subs`, `logs`, `kernel`, `overwrites` 等；`--full` 删全部，`-y` 跳过确认） |
132
+ | `mihomo dir open [target]` | 打开指定目录（`root`, `subs`, `logs`, `data`, `runtime`, `kernel`） |
133
+ | `mihomo reset [目标...] [--full] [-y]` | 重置用户数据（可用目标：`subs`, `logs`, `data`, `runtime`, `settings`, `kernel`, `overwrites`, `daemon`；`--full` 删全部，`-y` 跳过确认） |
129
134
  | `mihomo version` | 显示版本信息 |
130
135
  | `mihomo help` | 显示帮助信息 |
131
136
 
@@ -138,6 +143,8 @@ mihomo ui yacd # YACD
138
143
  - `mhm`
139
144
  - `mh`
140
145
 
146
+ 子命令组亦有别名：`subscription` = `sub`/`subs`/`subscriptions`，`directory` = `dir`/`dirs`/`directories`，`overwrite` = `ow`
147
+
141
148
  ### 快捷命令
142
149
 
143
150
  常用操作的快捷方式：
@@ -234,6 +241,35 @@ mihomo kernel --mirror-all hk.gh-proxy.org
234
241
  - 同一订阅 12 小时内只自动清理一次（冷却记录在订阅缓存），避免每次启动都全量测速
235
242
  - `--no-clean` 可跳过；随时可用 `mihomo clean` / `mihomo sub clean` 手动清理
236
243
 
244
+ ## 选项写法
245
+
246
+ 带值选项支持三种等价写法，长短选项对应关系：
247
+
248
+ | 短 | 长 | 用途 | 默认 |
249
+ | --- | --- | --- | --- |
250
+ | `-t` | `--timeout` | 测速超时（ms） | 2000 |
251
+ | `-j` | `--concurrency` | 测速并发数 | 100 |
252
+ | `-r` | `--rounds` | 清理时失败节点重试轮数 | 2 |
253
+ | `-u` | `--update-timeout` | 启动时自动更新订阅超时（ms） | 10000 |
254
+ | `-n` | `--lines` | 日志显示行数 | 100 |
255
+
256
+ ```bash
257
+ mihomo test -t 3000 # 短选项 + 空格
258
+ mihomo test --timeout 3000 # 长选项 + 空格
259
+ mihomo test --timeout=3000 # 长选项 + 等号
260
+ ```
261
+
262
+ 布尔开关：`-s`（跳过订阅更新）、`--no-update`、`--no-clean`、`-y`/`--yes`（跳过确认）、`-o`（用系统默认程序打开）。
263
+
264
+ 上述数值选项只接受 **>= 1 的整数**，非法值（`0`、负数、`5s`、`abc`）会直接报错而非静默取默认值——避免 `-j 0` 之类静默产出"全部节点失败"的假结果。
265
+
266
+ ## 数据保护
267
+
268
+ - **订阅内容校验**：下载到的内容必须含 `proxies` / `proxy-groups` / `proxy-providers` 之一才写盘。机场返回配额或错误 JSON（如 `{"error":"quota exceeded"}`）时报错并**保留磁盘上原有的可用配置**，不会被覆盖
269
+ - **`sub add` 失败回滚**：下载失败时移除半成品订阅，且不改动当前活跃订阅
270
+ - **`settings.json` 损坏恢复**：格式损坏（含合法 JSON 但非对象的情况）时自动备份为 `.bak` 并回退默认设置
271
+ - **`reset` 停止确认**：需要停止进程的重置会先确认进程真的已终止，未能停止时中止重置而非留下孤儿进程跑在已删配置上
272
+
237
273
  ## 数据目录
238
274
 
239
275
  用户数据存储位置（与安装位置分离，更新不丢失）：
@@ -254,7 +290,10 @@ mihomo kernel --mirror-all hk.gh-proxy.org
254
290
  ├── data/ # mihomo 运行数据（GeoIP 等，由内核自行管理）
255
291
  └── runtime/ # 运行时临时文件（stop 自动清除）
256
292
  ├── pid # 进程 PID
257
- └── config.yaml # 运行时生成的配置
293
+ ├── config.yaml # 运行时生成的配置
294
+ ├── 1.subscription.yaml # 分阶段调试：订阅原始配置
295
+ ├── 2.overwrite.yaml # 分阶段调试：应用覆写后
296
+ └── 3.system.yaml # 分阶段调试：合并系统配置后
258
297
  ```
259
298
 
260
299
  可通过环境变量 `MIHOMO_CLI_DIR` 自定义数据目录位置。
@@ -269,7 +308,7 @@ mihomo kernel --mirror-all hk.gh-proxy.org
269
308
  - `overwrite.yaml` — 主覆写文件
270
309
  - `overwrite.dns.yaml` — 按功能拆分的扩展文件（`overwrite.*.yaml` 格式）
271
310
  2. `overwrite.yaml` 始终最先加载，扩展文件按文件名排序加载
272
- 3. 使用 `mihomo ow on` 启用覆写配置（会自动重启）
311
+ 3. 覆写**默认即启用**，放好文件后重启生效（`mihomo start`）；如曾 `ow off` 禁用过，用 `mihomo ow on` 重新启用（会自动重启）
273
312
 
274
313
  ### 特殊语法
275
314
 
@@ -285,14 +324,16 @@ mihomo kernel --mirror-all hk.gh-proxy.org
285
324
 
286
325
  `~key` 用于**只修改数组里某一个元素的部分字段**，而不动其余元素、也不必复制整个元素。以 `name` 为主键匹配：命中同名元素则深度合并该元素，找不到则追加。典型用途：修改订阅下发的某个 `proxy-group` 的字段（如默认选中的节点），订阅更新后依然生效。
287
326
 
327
+ > `~key` / `+key` / `key+` 都是**数组语义**：若目标键已存在且不是数组（如 `~dns` 作用于映射、`log-level+` 作用于字符串），会直接报错而非静默包成单元素数组——后者会丢掉原有字段并生成 mihomo 无法解析的配置。要覆盖非数组值请用 `key!`（强制覆盖）或直接写 `key`（深度合并）。
328
+
288
329
  ### 作用域限定（match）
289
330
 
290
331
  在覆写文件顶部加 `match:` 块，可让该文件**只对指定订阅生效**（无 `match` 则全局生效）。所列条件需全部满足（AND），条件值为数组时其内部为 OR：
291
332
 
292
333
  | 匹配键 | 作用 |
293
334
  | ------------- | ----------------------------- |
294
- | `subscription` | 按订阅名精确匹配 |
295
- | `url-domain` | 按订阅 URL 的 hostname 后缀匹配 |
335
+ | `subscription` | 按订阅名匹配（大小写不敏感，与 `sub use` 口径一致） |
336
+ | `url-domain` | 按订阅 URL 的 hostname 后缀匹配（大小写不敏感） |
296
337
 
297
338
  ### 示例
298
339
 
@@ -363,7 +404,7 @@ sudo pkill -9 mihomo
363
404
 
364
405
  ## 安全特性
365
406
 
366
- - **URL 脱敏**：订阅 URL 中的 token、key、password 等敏感参数（含 query、userinfo 及路径型令牌）自动替换为 `***`
407
+ - **URL 脱敏**：订阅 URL 中的 token、key、password 等敏感参数（含 query、userinfo 及路径型令牌）自动替换为 `***`。逗号分隔的多源订阅逐段脱敏；query 内含逗号的单条 URL 不会被误拆（否则参数被劈开会导致 token 漏脱敏）
367
408
  - **文件权限**：配置文件使用 `0o600` 权限（仅所有者可读可写），目录使用 `0o700` 权限
368
409
  - **入站默认关闭**：订阅/覆写未指定时 `allow-lan` 默认 `false`；如需局域网设备连入代理端口，可在订阅或覆写中显式开启
369
410
  - **信号处理**：优雅处理 SIGINT/SIGTERM 信号