> ## Documentation Index
> Fetch the complete documentation index at: https://yumebox.gal.tf/llms.txt
> Use this file to discover all available pages before exploring further.

# 示例与排错

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

## 修改端口和模式

```yaml 基础字段.yaml icon="file-code" lines theme={null}
mixed-port: 7890
mode: rule
```

```yaml 基础字段 diff.yaml icon="file-code" lines theme={null}
mixed-port: 10801 # [!code --]
mixed-port: 7890 # [!code ++]
mode: global # [!code --]
mode: rule # [!code ++]
```

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

## 修改 DNS

### 递归修改

```yaml DNS 子字段.yaml icon="file-code" lines theme={null}
dns:
  enable: true
  enhanced-mode: fake-ip
```

```yaml DNS 子字段 diff.yaml icon="file-code" lines theme={null}
dns:
  enable: false # [!code --]
  enable: true # [!code ++]
  enhanced-mode: fake-ip # [!code ++]
  nameserver:
    - 223.5.5.5
```

### 完整替换

```yaml DNS 完整替换.yaml icon="file-code" lines theme={null}
dns-force:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
```

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

## 添加直连规则

```yaml 添加直连规则.yaml icon="file-code" lines theme={null}
rules-start:
  - DOMAIN-SUFFIX,baidu.com,DIRECT
  - DOMAIN-SUFFIX,tencent.com,DIRECT
```

```yaml 添加直连规则 diff.yaml icon="file-code" lines theme={null}
rules:
  - DOMAIN-SUFFIX,baidu.com,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,tencent.com,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,old.example,PROXY
  - MATCH,PROXY
```

## 添加 Provider

```yaml 添加规则 Provider.yaml icon="file-code" lines theme={null}
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 修改策略组.yaml icon="file-code" lines theme={null}
proxy-groups-end:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
```

```yaml 修改策略组 diff.yaml icon="file-code" lines theme={null}
proxy-groups:
  - name: PROXY # [!code --]
    type: url-test # [!code --]
    proxies: # [!code --]
      - AUTO # [!code --]
  - name: PROXY # [!code ++]
    type: select # [!code ++]
    proxies: # [!code ++]
      - DIRECT # [!code ++]
```

## YAML 锚点和 `<<`

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

```yaml 使用锚点.yaml icon="file-code" lines theme={null}
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
```

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

```yaml 锚点覆盖结果 diff.yaml icon="file-code" lines theme={null}
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 解析成数字.

```yaml Reality short-id.yaml icon="file-code" lines theme={null}
proxies-end:
  - name: 示例节点
    type: vless
    server: example.com
    port: 443
    reality-opts:
      short-id: 0123
```

```yaml Reality short-id 预期.yaml icon="file-code" lines theme={null}
reality-opts:
  short-id: "0123"
```

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

## 字面量键

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

```yaml 字面量键.yaml icon="file-code" lines theme={null}
<rules+>:
  enabled: true
```

```yaml 字面量键结果 diff.yaml icon="file-code" lines theme={null}
rules+:
  enabled: true # [!code ++]
```

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

## 多个覆写文件

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

```yaml 第一个覆写.yaml icon="file-code" lines theme={null}
mixed-port: 7890
rules-start:
  - DOMAIN-SUFFIX,first.example,DIRECT
```

```yaml 第二个覆写.yaml icon="file-code" lines theme={null}
mixed-port: 7891
rules-end:
  - DOMAIN-SUFFIX,last.example,DIRECT
```

```yaml 覆写链最终 diff.yaml icon="file-code" lines theme={null}
mixed-port: 7890 # [!code --]
mixed-port: 7891 # [!code ++]
rules:
  - DOMAIN-SUFFIX,first.example,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,original.example,DIRECT
  - DOMAIN-SUFFIX,last.example,DIRECT # [!code ++]
  - MATCH,PROXY
```

## 空文件

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

```yaml 空覆写.yaml icon="file-code" lines theme={null}
```

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

## YAML 解析错误

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

```yaml 错误的缩进.yaml icon="file-code" lines theme={null}
proxy-groups:
  -
  name: PROXY
```

预期结果：

```text theme={null}
parse yaml override <覆写文件路径>: <YAML 解析错误>
```

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

## 错误的根类型

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

```yaml 错误的根类型.yaml icon="file-code" lines theme={null}
- this-is-a-list
```

预期结果：

```text theme={null}
compiled root config must be an object
```

## `geosite-matcher` 校验错误

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

```yaml 错误的 Matcher.yaml icon="file-code" lines theme={null}
geosite-matcher: unknown
```

预期结果：

```text theme={null}
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 入口.                                       |

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