# 验证与排错

Source: https://onexray.com/zh/docs/troubleshooting/
Description: 区分 JSON 语法、导入兼容、内核构造、平台启动与真实连通性。


## 分层验证

1. 语法：严格 JSON、根对象，没有未替换占位符。
2. 导入规范：入口、封装、空槽、动作、字段、名称与数量满足 App 要求。
3. 依赖：DAT 文件和分类存在，自定义名称不冲突，URL 真实。
4. App 保存：实际导入/编辑流程调用 libXray 对投影配置构造实例并关闭。
5. 运行：经用户授权并满足权限、网卡条件后启动；保存成功不代表启动成功。
6. 行为：验证所需代理、直连、阻断目标及 DNS，说明实际执行过哪些检查。

不能直接用带空槽的自定义文件启动命令行 Xray。App 在验证时生成临时出站，运行时选择真实节点。校验不是远端服务器在线测试。

## 常见问题

| 表现 | 检查与处理 |
| --- | --- |
| JSON 立即拒绝 | 完整错误、严格 JSON、根类型、正确入口 |
| 自定义不支持字段 | 不需要才移除；否则选支持的模式/版本，不能丢掉需求 |
| outbounds 错误 | 自定义以 1–3 空对象开头，高级可追加辅助出站；节点/Raw 为真实出站 |
| 常规自定义 DNS 错误 | 固定 tag/address 结构；一条 app-dns-direct，启用 FakeDNS 时另加一条 address 为 fakedns 的 app-dns-fake |
| 内网域名失败 | 智能/常规：纯域名直连规则、本地 DNS 和直连可达性。高级/Raw：检查用户的 DNS 与解析路由链；只改 TUN DNS 通常不够 |
| DAT/分类不存在 | 查看已安装分类，修正规则或显式导入真实依赖 |
| 默认 Geodata 更新失败 | 保留旧文件；单凭这条日志不能判断 VPN 启动原因 |
| 可保存但无法启动 | 实际启动错误、凭据、端口、权限、网卡、平台限制 |
| IP 直连规则不生效 | 更早的域名/无条件规则可能阻止第二轮 |
| 没有按预期均衡 | 未命中使用第一出站，显式 balancer 规则才均衡 |
| VPN 开启时延迟不真实 | 测速可能经过当前 VPN；关闭后测试真实节点路径 |
| FakeDNS 重启后失效 | 旧虚拟地址缓存超出映射生命周期，重新查询 DNS/重启相关应用并检查排除路由 |

## 安全报告

索取完整相关错误，而不是只说“失败”。配置仅提供诊断必需的脱敏部分，并说明哪些结构必须保留。UUID、密码、token、私钥和订阅 URL 可能敏感，不要求公开。

只阅读源码或检查 JSON 不能声称“已验证可用”，含虚构凭据的模板不是可联网服务。

## 文档验收场景

仅向助手提供完整指南和需求，核对：VLESS 导入、公司 DNS、中国大陆直连/GitHub 代理、不支持 Custom 字段、协议/系统匹配、FakeDNS、旧版兼容、双接入链路、缺少凭据、Android 应用、Apple Wi-Fi、Windows 网卡、DAT 分类缺失、保存成功但启动失败。

结果应选对模式或 UI 操作，需要时给完整配置，缺资料时询问，并诚实说明验证范围。这是评估标准，不表示已经完成独立模型盲测。

## 备份与恢复排错

- **无法读取或写入备份**：检查保存位置、系统授权和存储提供程序是否可用。云端文件可能需要先下载；本地写入成功不证明已上传云端。
- **恢复订阅后没有节点**：备份保留订阅来源，不保留节点缓存。更新订阅以获取节点；手动节点和完整 Raw JSON 则直接恢复。
- **恢复路由后缺少 GeoData**：待下载来源不阻塞配置记录恢复，但依赖它的路由需要实际文件。必要时先使用其他可用配置连接，再到路由数据页下载；不要删除规则或期待 VPN 启动时自动下载。

恢复范围和替换行为见[备份指南](https://onexray.com/zh/docs/backup/)。不要将未加密备份公开作为诊断附件，其中可能包含节点凭据、Age 私钥和 HWID。