> ## 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.
# FAQ
本页按错误文本定位问题。弹窗中的 `启动失败：...` 通常只是外层提示，真正原因位于冒号后的错误，或启动日志中的最后一条 `core|` 记录。
在「设置 → 关于 → 导出日志」生成诊断 ZIP。
核对内核字段、代理协议和规则格式。
附上版本、内核版本、运行模式和脱敏日志。
日志和配置可能包含订阅地址、节点密码、UUID、Token、域名及 IP。公开提交前必须脱敏，不要上传完整订阅文件。
## 先做这四步
不要只记录“启动失败”。复制完整错误，尤其是 `parse source yaml:`、`rules[n]`、`proxy [...] not found` 等前缀和索引。
在网络设置中启用「禁用所有覆写」，重新启动一次。若能够启动，问题位于 YAML/JavaScript 覆写或可视化分流配置。
先使用 `VPN Service` 验证配置。只有 Root `Tun` / `TPROXY` 失败时，优先检查 Root 授权、SELinux、路由和 iptables。
复现后立即进入「设置 → 关于 → 导出日志」。ZIP 会包含本地 VPN、Root 启动记录和 `core.log`。
## 配置与内核错误
下面的错误文本来自当前 Rust 配置编译器、Android 启动链路和 mihomo 内核。错误后的名称与索引会因配置不同而变化。
```text 常见错误 theme={null}
parse source yaml: ...
yaml: unmarshal errors: ...
```
YAML 语法或字段类型错误。常见原因是缩进混用、冒号后缺少空格、Tab 缩进、字符串未加引号，或把对象字段写成列表。
处理顺序：
1. 在应用编辑器中打开原配置和已启用覆写，先修复标记的行列。
2. 确认顶层是 YAML object，而不是数组或单个字符串。
3. 暂停所有覆写后重试，区分错误来自订阅还是覆写。
编译后的顶层配置不是 object。常见于配置文件只有 `- item`，或 JavaScript 覆写返回数组、字符串、`null`。
YAML 顶层应类似：
```yaml 正确的顶层结构 theme={null}
mixed-port: 7890
proxies: []
proxy-groups: []
rules:
- MATCH,DIRECT
```
JavaScript `main(profile)` 必须返回 object 或 resolve 为 object 的 Promise。
```text 内核错误 theme={null}
rules[12] [...] error: format invalid
```
第 `n` 条规则缺少类型、匹配内容或目标策略组。根据错误中的完整规则检查逗号数量和顺序。
```yaml 规则示例 theme={null}
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- MATCH,PROXY
```
```text 内核错误 theme={null}
rules[8] [...] error: proxy [PROXY] not found
proxy [node-a] dialer-proxy [relay] not found
tunnel proxy PROXY not found
```
规则目标、`dialer-proxy` 或 tunnel 引用了不存在的节点/策略组。名称区分大小写，并且必须与 `proxies[].name` 或 `proxy-groups[].name` 完全一致。
若名称由覆写新增，检查覆写应用顺序；删除策略组时也要同步修改引用它的规则。
```text 内核错误 theme={null}
rules[3] [...] error: rule set [private] not found
dns.fake-ip-filter[0] [...] error: rule-set 'private' not found
```
`RULE-SET`、DNS 或 Tun 字段引用了不存在的 `rule-providers` 名称。
provider 名称必须与规则引用完全一致。
必须与 provider 文件内容格式匹配。
```text 内核错误 theme={null}
format error
unsupported type
group-name: `use` or `proxies` missing
duplicate provider name
```
策略组缺少 `name`、`type`，类型不受当前内核支持，或没有任何节点来源。
策略组名称，不能留空。
例如 `select`、`url-test`、`fallback`、`load-balance`。
至少提供直接节点列表或 proxy provider 列表之一。
```text 常见错误 theme={null}
decrypt config error: ...
decrypt age profile: ...
no supported age secret keys found
parse age secret key at line ...
This config is encrypted with age. Please provide the age secret key ...
```
配置已用 Age 加密，但导入时没有提供匹配的 identity，或 secret key 格式不受支持。
* 使用私钥/identity，不要填写 recipient 公钥。
* 多个 key 每行一个，删除行首行尾空格。
* 重新导入配置并填写密钥；仅修改普通配置名称不会补充密钥。
* 不要把私钥发到 Issue、群聊或截图中。
订阅或外部 provider 返回了失败状态。YumeBox 不会把 HTTP 错误页面当作有效订阅配置。
确认地址未过期、未被截断，并能在当前网络访问。
某些 provider 需要鉴权 Header；检查配置中 Header 名称和值。
`401/403` 通常是 Token、UA 或访问策略问题；`404` 通常是路径失效；`5xx` 表示服务端暂时异常。
YumeBox 会在导入时预取 `proxy-providers` 和 `rule-providers`，内核运行后也会负责缺失资源。下载失败时检查：
URL 必须为可访问的 HTTP(S) 地址。
需要联网下载的 provider 通常使用 `http`。
建议使用相对路径。绝对路径或越过 profile 目录的路径会被重写或拒绝。
还要确认 provider 返回的是 mihomo provider YAML/MRS，而不是网页、登录页或普通订阅链接。
编译后的 provider `path` 逃出了当前配置的私有 `providers/rules` 或 `providers/proxies` 目录。此检查用于避免不同订阅互相覆盖资源。
删除覆写中的绝对路径、`../`、旧的 `./ruleset/` 和带 `/clash/` 的路径，让 YumeBox 按 provider 名称生成隔离路径。
支持的覆写扩展名只有 `.yaml`、`.yml` 和 `.js`。
```text 常见错误 theme={null}
unsupported override extension: ...
parse yaml override ...
脚本执行失败：...
JS override result must be an object
JS override rejected: ...
async main(profile) did not settle
```
先单独停用最近添加的覆写。JavaScript 覆写必须定义 `main(profile)` 并返回 object；异步函数必须在有限时间内 resolve。更多语法见 [YAML API](/override/yaml) 与 [JavaScript API](/override/js-override)。
```text 内核启动错误 theme={null}
mihomo: parse compiled config: ...
Parse config error: ...
```
这是内核解析阶段的外层错误。真正原因位于同一行后半部分，常见为规则引用、策略组、DNS、Tun 或代理协议字段不合法。按后半部分文本在本页继续搜索。
## VPN、Root 与启动错误
Android 没有返回可用的 VPN interface。
* 接受系统 VPN 授权弹窗。
* 停止其他 VPN、工作资料 VPN 或始终开启的 VPN。
* 在系统设置中撤销 YumeBox 的 VPN 授权后重新授权。
* 厂商系统若限制后台启动，为 YumeBox 开启后台运行权限。
```text Root 启动错误 theme={null}
root core launch failed (success=false ...)
Tun / TPROXY 需要 YumeBox 已获取可用的 Root 权限
```
`Tun` 与 `TPROXY` 运行模式需要可用的 `su`。确认 Root 管理器已授权当前安装包，并且授权没有被设置为“仅一次”。更新或更换签名后，Root 管理器可能把应用视为新客户端，需要重新授权。
内核创建 Tun、写路由、执行 iptables 或运行 native binary 时被系统拒绝。
* `VPN Service` 下出现：检查系统 VPN 授权和 ROM 后台限制。
* Root `Tun` 下出现：检查 `su` 授权、SELinux 策略和 `/dev/net/tun`。
* `TPROXY` 下出现：确认内核支持 TPROXY，系统具有 iptables 相关模块。
* 仅自编译 APK 出现：确认对应 ABI 的四个 native 文件均已打包。
Root 进程可能仍存在，但 controller Unix socket 未准备好或内核已在启动后退出。导出日志并查看 `core.log` 最后一行；常见根因仍是配置解析失败、配置管道读取失败或 socket 创建失败。
先停止代理，确认没有残留 Root daemon，再重新启动。不要只根据通知栏是否存在判断内核是否可用。
启动协调器没有在预期时间内看到 Running 状态。可能是内核阻塞、Root daemon 未响应、controller 不可访问或系统冻结了后台服务。
处理顺序：停止服务、强制结束应用、重新打开后使用 `VPN Service` 启动；若仍失败，立即导出日志。不要连续快速点击启动按钮，这会让旧状态更难判断。
## 常见现象
先启动代理，再进入外部资源页面确认 proxy provider 是否存在。
* 内联节点应位于顶层 `proxies`。
* 外部节点应位于 `proxy-providers`，并通过策略组的 `use` 引用。
* provider 名称区分大小写。
* provider 下载失败时检查 URL、Header、文件格式和当前网络。
外部 provider 节点由 `/providers/proxies` 提供，而普通节点来自 `/proxies`。先确认内核已启动且 provider 已成功加载，再刷新代理页面。
若只有某种新协议显示 `Unknown`，记录 `/providers/proxies` 返回的 `type` 或导出日志，并附上 YumeBox 与内核版本提交 Issue。不要附带节点凭据。
若 DIRECT 也无法联网，优先检查 VPN/Tun、DNS 劫持、IPv6 和访问控制。
暂时使用配置中的普通 DNS，停用可疑的 fake-ip filter、rule-set 和覆写后重试。
确认最终 `MATCH` 指向存在且包含可用节点的策略组。
使用 external APK 时，首次启动需要下载 Geo 资源。网络受限时可改用 builtin APK。
`external` APK 不携带 Geo 数据，文件较小，首次使用依赖网络；`builtin` APK 携带 GeoIP、GeoSite、ASN 和 BundleMRS，文件较大但不依赖首次下载。两者的应用功能与内核代码相同。
至少提供以下信息：
关于页显示的版本号与安装来源。
关于页中的 mihomo 分支和短 hash。
同一配置在其他模式是否能够启动。
包含完整前缀、索引和末尾原因。
从关于页导出，公开上传前删除凭据和隐私信息。
查看 Android SDK、NDK、Go、Rust、native 和 APK 的完整构建流程。