FAQ - YumeBox

本页按错误文本定位问题。弹窗中的 启动失败：... 通常只是外层提示，真正原因位于冒号后的错误，或启动日志中的最后一条 core| 记录。

导出启动日志

在「设置 → 关于 → 导出日志」生成诊断 ZIP。

mihomo 配置文档

核对内核字段、代理协议和规则格式。

提交 Issue

附上版本、内核版本、运行模式和脱敏日志。

日志和配置可能包含订阅地址、节点密码、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 内核。错误后的名称与索引会因配置不同而变化。

parse source yaml / yaml: unmarshal errors

常见错误

parse source yaml: ...
yaml: unmarshal errors: ...

YAML 语法或字段类型错误。常见原因是缩进混用、冒号后缺少空格、Tab 缩进、字符串未加引号，或把对象字段写成列表。处理顺序：

在应用编辑器中打开原配置和已启用覆写，先修复标记的行列。
确认顶层是 YAML object，而不是数组或单个字符串。
暂停所有覆写后重试，区分错误来自订阅还是覆写。

compiled root config must be an object

编译后的顶层配置不是 object。常见于配置文件只有 - item，或 JavaScript 覆写返回数组、字符串、null。YAML 顶层应类似：

正确的顶层结构

mixed-port: 7890
proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

JavaScript main(profile) 必须返回 object 或 resolve 为 object 的 Promise。

rules[n] ... format invalid

内核错误

rules[12] [...] error: format invalid

第 n 条规则缺少类型、匹配内容或目标策略组。根据错误中的完整规则检查逗号数量和顺序。

规则示例

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,PROXY

proxy [name] not found

内核错误

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 完全一致。若名称由覆写新增，检查覆写应用顺序；删除策略组时也要同步修改引用它的规则。

rule set [name] not found

内核错误

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 名称。

object

必填

provider 名称必须与规则引用完全一致。

domain | ipcidr | classical

必填

必须与 provider 文件内容格式匹配。

策略组 format error / unsupported type / use or proxies missing

内核错误

format error
unsupported type
group-name: `use` or `proxies` missing
duplicate provider name

策略组缺少 name、type，类型不受当前内核支持，或没有任何节点来源。

string

必填

策略组名称，不能留空。

string

必填

例如 select、url-test、fallback、load-balance。

string[]

必填

至少提供直接节点列表或 proxy provider 列表之一。

Age 解密失败

常见错误

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、群聊或截图中。

HTTP 401 / 403 / 404 / 5xx

订阅或外部 provider 返回了失败状态。YumeBox 不会把 HTTP 错误页面当作有效订阅配置。

http | https

必填

确认地址未过期、未被截断，并能在当前网络访问。

object

某些 provider 需要鉴权 Header；检查配置中 Header 名称和值。

401/403 通常是 Token、UA 或访问策略问题；404 通常是路径失效；5xx 表示服务端暂时异常。

Provider download failed / 外部节点为空

YumeBox 会在导入时预取 proxy-providers 和 rule-providers，内核运行后也会负责缺失资源。下载失败时检查：

string

必填

URL 必须为可访问的 HTTP(S) 地址。

http | file | inline

需要联网下载的 provider 通常使用 http。

string

建议使用相对路径。绝对路径或越过 profile 目录的路径会被重写或拒绝。

还要确认 provider 返回的是 mihomo provider YAML/MRS，而不是网页、登录页或普通订阅链接。

Compiled provider path escaped profile scope

编译后的 provider path 逃出了当前配置的私有 providers/rules 或 providers/proxies 目录。此检查用于避免不同订阅互相覆盖资源。删除覆写中的绝对路径、../、旧的 ./ruleset/ 和带 /clash/ 的路径，让 YumeBox 按 provider 名称生成隔离路径。

unsupported override extension / 覆写执行失败

支持的覆写扩展名只有 .yaml、.yml 和 .js。

常见错误

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 与 JavaScript API。

mihomo: parse compiled config

内核启动错误

mihomo: parse compiled config: ...
Parse config error: ...

这是内核解析阶段的外层错误。真正原因位于同一行后半部分，常见为规则引用、策略组、DNS、Tun 或代理协议字段不合法。按后半部分文本在本页继续搜索。

VPN、Root 与启动错误

VPN 权限被拒绝 / Establish VPN rejected by system

Android 没有返回可用的 VPN interface。

接受系统 VPN 授权弹窗。
停止其他 VPN、工作资料 VPN 或始终开启的 VPN。
在系统设置中撤销 YumeBox 的 VPN 授权后重新授权。
厂商系统若限制后台启动，为 YumeBox 开启后台运行权限。

root core launch failed

Root 启动错误

root core launch failed (success=false ...)
Tun / TPROXY 需要 YumeBox 已获取可用的 Root 权限

Tun 与 TPROXY 运行模式需要可用的 su。确认 Root 管理器已授权当前安装包，并且授权没有被设置为“仅一次”。更新或更换签名后，Root 管理器可能把应用视为新客户端，需要重新授权。

permission denied / operation not permitted

内核创建 Tun、写路由、执行 iptables 或运行 native binary 时被系统拒绝。

VPN Service 下出现：检查系统 VPN 授权和 ROM 后台限制。
Root Tun 下出现：检查 su 授权、SELinux 策略和 /dev/net/tun。
TPROXY 下出现：确认内核支持 TPROXY，系统具有 iptables 相关模块。
仅自编译 APK 出现：确认对应 ABI 的四个 native 文件均已打包。

root core controller unavailable

Root 进程可能仍存在，但 controller Unix socket 未准备好或内核已在启动后退出。导出日志并查看 core.log 最后一行；常见根因仍是配置解析失败、配置管道读取失败或 socket 创建失败。先停止代理，确认没有残留 Root daemon，再重新启动。不要只根据通知栏是否存在判断内核是否可用。

runtime activation timed out / 启动一直停留在启动中

启动协调器没有在预期时间内看到 Running 状态。可能是内核阻塞、Root daemon 未响应、controller 不可访问或系统冻结了后台服务。处理顺序：停止服务、强制结束应用、重新打开后使用 VPN Service 启动；若仍失败，立即导出日志。不要连续快速点击启动按钮，这会让旧状态更难判断。

常见现象

配置导入成功，但代理组没有节点

先启动代理，再进入外部资源页面确认 proxy provider 是否存在。

内联节点应位于顶层 proxies。
外部节点应位于 proxy-providers，并通过策略组的 use 引用。
provider 名称区分大小写。
provider 下载失败时检查 URL、Header、文件格式和当前网络。

节点协议显示 Unknown

外部 provider 节点由 /providers/proxies 提供，而普通节点来自 /proxies。先确认内核已启动且 provider 已成功加载，再刷新代理页面。若只有某种新协议显示 Unknown，记录 /providers/proxies 返回的 type 或导出日志，并附上 YumeBox 与内核版本提交 Issue。不要附带节点凭据。

已连接但无法访问网络

切换到 DIRECT 验证 Tun

若 DIRECT 也无法联网，优先检查 VPN/Tun、DNS 劫持、IPv6 和访问控制。

检查 DNS

暂时使用配置中的普通 DNS，停用可疑的 fake-ip filter、rule-set 和覆写后重试。

检查规则目标

确认最终 MATCH 指向存在且包含可用节点的策略组。

检查 Geo 数据

使用 external APK 时，首次启动需要下载 Geo 资源。网络受限时可改用 builtin APK。

外置 Geo 和内置 Geo 有什么区别

external APK 不携带 Geo 数据，文件较小，首次使用依赖网络；builtin APK 携带 GeoIP、GeoSite、ASN 和 BundleMRS，文件较大但不依赖首次下载。两者的应用功能与内核代码相同。

如何提交可处理的问题报告

至少提供以下信息：

string

必填

关于页显示的版本号与安装来源。

branch + commit

必填

关于页中的 mihomo 分支和短 hash。

VPN Service | Tun | TPROXY

必填

同一配置在其他模式是否能够启动。

string

必填

包含完整前缀、索引和末尾原因。

ZIP

必填

从关于页导出，公开上传前删除凭据和隐私信息。

从源码构建

查看 Android SDK、NDK、Go、Rust、native 和 APK 的完整构建流程。

导出启动日志

mihomo 配置文档

提交 Issue

​先做这四步

​配置与内核错误

​VPN、Root 与启动错误

​常见现象

从源码构建

先做这四步

配置与内核错误

VPN、Root 与启动错误

常见现象