示例与排错

本页展示可以直接保存的完整覆写，以及常见错误的实际预期.

修改端口和模式

基础字段.yaml

mixed-port: 7890
mode: rule

基础字段 diff.yaml

mixed-port: 10801
mixed-port: 7890
mode: global
mode: rule

mixed-port 和 mode 都是标量，普通键会直接覆盖原值.

修改 DNS

递归修改

DNS 子字段.yaml

dns:
  enable: true
  enhanced-mode: fake-ip

DNS 子字段 diff.yaml

dns:
  enable: false
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5

完整替换

DNS 完整替换.yaml

dns-force:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1

dns-force 会删除原 dns 对象中的其他字段，只保留上面的内容.

添加直连规则

添加直连规则.yaml

rules-start:
  - DOMAIN-SUFFIX,baidu.com,DIRECT
  - DOMAIN-SUFFIX,tencent.com,DIRECT

添加直连规则 diff.yaml

rules:
  - DOMAIN-SUFFIX,baidu.com,DIRECT
  - DOMAIN-SUFFIX,tencent.com,DIRECT
  - DOMAIN-SUFFIX,old.example,PROXY
  - MATCH,PROXY

添加 Provider

添加规则 Provider.yaml

rule-providers-merge:
  local:
    type: http
    behavior: domain
    format: yaml
    interval: 86400
    url: https://example.com/local.yaml
    path: ./ruleset/local.yaml

rules-end:
  - RULE-SET,local,PROXY

运行时补丁会将 Provider 路径规范化到当前配置目录下，避免相对路径离开配置作用域.

修改策略组

修改策略组.yaml

proxy-groups-end:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

修改策略组 diff.yaml

proxy-groups:
  - name: PROXY
    type: url-test
    proxies: 
      - AUTO
  - name: PROXY
    type: select
    proxies: 
      - DIRECT

YAML 锚点和 `<<`

覆写文件会先由 YAML 解析器展开锚点、别名和 << 合并键.

使用锚点.yaml

provider-default: &provider-default
  type: http
  interval: 86400
  behavior: domain
  format: yaml

rule-providers-merge:
  example:
    <<: *provider-default
    url: https://example.com/rules.yaml
    path: ./ruleset/example.yaml

显式字段优先于锚点内容：

锚点覆盖结果 diff.yaml

example:
  type: http
  interval: 86400
  behavior: domain
  format: yaml
  url: https://example.com/rules.yaml
  path: ./ruleset/example.yaml

`reality-opts.short-id`

YumeBox 会保护顶层 proxies 列表中 reality-opts.short-id 的字符串值.这样 0123 和 1e5 不会被 YAML 解析成数字.

Reality short-id.yaml

proxies-end:
  - name: 示例节点
    type: vless
    server: example.com
    port: 443
    reality-opts:
      short-id: 0123

Reality short-id 预期.yaml

reality-opts:
  short-id: "0123"

嵌套在其他自定义对象中的 short-id 不会触发这个专用保护.

字面量键

尖括号会关闭修饰符解析，并在编译时去掉尖括号：

字面量键.yaml

<rules+>:
  enabled: true

字面量键结果 diff.yaml

rules+:
  enabled: true

未包裹时，rules+ 会被解析成向 rules 追加；包裹后才会写入名为 rules+ 的字段.

多个覆写文件

覆写文件按照订阅中的绑定顺序执行，后一个文件可以修改前一个文件的结果.

第一个覆写.yaml

mixed-port: 7890
rules-start:
  - DOMAIN-SUFFIX,first.example,DIRECT

第二个覆写.yaml

mixed-port: 7891
rules-end:
  - DOMAIN-SUFFIX,last.example,DIRECT

覆写链最终 diff.yaml

mixed-port: 7890
mixed-port: 7891
rules:
  - DOMAIN-SUFFIX,first.example,DIRECT
  - DOMAIN-SUFFIX,original.example,DIRECT
  - DOMAIN-SUFFIX,last.example,DIRECT
  - MATCH,PROXY

空文件

空文件或只包含空白字符的文件会被跳过，不会修改配置：

空覆写.yaml

编译结果会成功，但 warnings 中会出现 skip empty override file.

YAML 解析错误

缩进错误、非法映射或未闭合字符串会停止当前覆写链：

错误的缩进.yaml

proxy-groups:
  -
  name: PROXY

预期结果：

parse yaml override <覆写文件路径>: <YAML 解析错误>

错误信息会包含覆写文件路径，后续覆写不会继续执行.

错误的根类型

YAML 顶层不是对象时，覆写引擎会把根配置替换成该值；随后编译器会拒绝它：

错误的根类型.yaml

- this-is-a-list

预期结果：

compiled root config must be an object

`geosite-matcher` 校验错误

覆写本身可以写入字符串，但最终校验只接受 mph 和 succinct：

错误的 Matcher.yaml

geosite-matcher: unknown

预期结果：

geosite-matcher must be one of: mph, succinct

运行时边界

用户覆写完成后，YumeBox 仍会执行运行时补丁：

场景	最终行为
DNS 未启用	补充默认 DNS、`fake-ip` 和过滤项.
`Vpn Service` 或 `eBPF`	关闭 `tun.enable`、`auto-route` 和 `auto-detect-interface`.
`Tun`	保留配置中的 Tun 设置.
`listeners`	移除 `redir` 和 `tun` 类型监听器.
配置预览	清空端口、监听器和 Tun 入口.

因此，覆写成功不代表所有字段都会成为最终运行值；运行模式相关设置可能在最后被应用补丁调整.

开始

指南

覆写

更多

修改端口和模式

修改 DNS

递归修改

完整替换

添加直连规则

添加 Provider

修改策略组

YAML 锚点和 `<<`

`reality-opts.short-id`

字面量键

多个覆写文件

空文件

YAML 解析错误

错误的根类型

`geosite-matcher` 校验错误

运行时边界

​修改端口和模式

​修改 DNS

​递归修改

​完整替换

​添加直连规则

​添加 Provider

​修改策略组

​YAML 锚点和 <<

​reality-opts.short-id

​字面量键

​多个覆写文件

​空文件

​YAML 解析错误

​错误的根类型

​geosite-matcher 校验错误

​运行时边界

修改端口和模式

修改 DNS

递归修改

完整替换

添加直连规则

添加 Provider

修改策略组

YAML 锚点和 `<<`

`reality-opts.short-id`

字面量键

多个覆写文件

空文件

YAML 解析错误

错误的根类型

`geosite-matcher` 校验错误

运行时边界