从一次连接失败切入
连接 HarmonyOS NEXT 设备上的 Hey，点击开始，界面停在连接中，随后回到未连接状态。系统 VPN 指示没有出现，或者出现后立刻消失。此时最容易怀疑节点或网络，但真正的问题往往在授权链路、VPN Extension 的启动路径或配置来源。排查应从最靠近系统的一层开始，而不是先换节点。
Hey 是 HarmonyOS NEXT 上的 ArkTS 应用，连接动作本质是启动 HarmonyOS VPN Extension，断开动作是停止该 Extension。Xray 在应用内有两种运行模式：VPN 模式和仅代理模式。理解这两点，后面的每一步才有落点。
第一步：确认授权是否真正下发
VPN Extension 的启动依赖系统 VPN 授权。授权没有下发时，应用侧只能看到启动失败或启动后被系统终止，表现与网络故障高度相似。
授权现象的判断
开始连接后，观察系统是否弹出 VPN 授权请求。没有弹窗，说明请求没有到达系统授权组件；弹窗出现但确认后仍失败，说明授权组件存在而 Extension 启动被拒；系统 VPN 指示短暂出现又消失，说明 Extension 已启动但随即退出，问题更可能在 Extension 内部而非授权。
要点：授权请求没有出现，优先排查授权组件是否存在，而不是排查节点连通性。
Hey VPN Extension 授权的检查顺序
- 确认当前应用是通过仓库自行构建并签名的安装包，签名信息与设备信任链一致。
- 确认设备系统镜像包含 VPN 授权相关组件，部分裁剪镜像会缺失该组件。
- 确认系统中没有其他 VPN 应用长期占用授权入口，导致新请求被排队或拒绝。
- 卸载后重新安装，再次触发授权请求，观察系统是否弹出授权界面。
- 若始终无弹窗，转向模拟器与镜像层面的排查，见后文差异一节。
第二步：区分 VPN 模式与仅代理模式
两种模式的运行路径不同，失败位置也不同。VPN 模式需要启动 HarmonyOS VPN Extension 承接流量；仅代理模式不依赖 Extension 的流量接管，主要用于验证 Xray 本身能否正常工作。
运行路径的排查方法
- 先切到仅代理模式发起连接。若仅代理模式可用，说明配置与出站本身没有问题，故障集中在 Extension 启动与授权。
- 再切回 VPN 模式。若此时失败，重点看 Extension 的启动返回结果与系统日志。
- 断开时观察 Extension 是否被正确停止。停止失败会留下残留状态，下一次启动可能直接失败。
- 反复开始与停止若干次，确认状态机没有卡在中间态。
使用 sing-box 时需注意：目前在 VPN 模式下只支持单个转换后的 outbound。配置里出现多个候选出站，可能表现为连接建立后立即断开，或启动阶段直接报错。这不是授权问题，但现象接近，需要用仅代理模式交叉验证。
要点：仅代理模式能通、VPN 模式不通，问题在 Extension 与授权；两种模式都不通，问题在配置来源或 Xray 出站。
第三步：检查配置来源
配置从外部进入应用有多个入口：外部深链、系统分享、扫码。这三个入口都会先展示目标内容并等待确认，不会静默导入。排查时容易误判为“配置已生效”，实际仍在等待确认或确认后未写入。
配置来源的排查顺序
- 确认外部深链打开后，目标内容页面已经出现，并且确认动作已完成。
- 确认系统分享进入时，分享内容被正确解析为目标配置，而不是被当作普通文本。
- 确认扫码结果展示后已完成确认，且配置确实保存到当前使用的配置集中。
- 确认当前连接使用的是刚确认的配置，而不是上一次遗留的配置。
- 若配置中含多个出站且使用 sing-box，收敛为单个转换后的 outbound 再试。
仓库不提供预编译安装包，需要自行构建和签名。构建产物与配置格式不匹配时，配置可能被解析为不完整结构，表现为连接立即失败。此时应回到构建流程确认产物来源一致。
第四步：用日志确定失败环节
日志的作用是把“连不上”拆成具体阶段：授权请求、Extension 启动、Extension 停止、配置解析、出站建立。按阶段读日志，比反复重连有效。
日志观察顺序
- 先看授权相关记录，确认请求是否发出、系统是否回应、回应结果是什么。
- 再看 Extension 启停记录，确认启动调用是否有返回，停止是否成功。
- 然后看配置解析记录，确认配置被完整读取，出站数量符合当前模式限制。
- 最后看出站建立记录，确认失败发生在本地还是远端。
- 把失败时刻的日志与操作时刻对齐，排除旧日志干扰。
要点：日志里没有授权请求记录，就不要继续分析出站错误。
第五步：真机与模拟器的差异
Hey 模拟器 VPN 授权问题是高频场景。部分模拟器或系统镜像没有 VPN 授权组件，授权请求无法被处理，表现为点击连接后无弹窗、无 VPN 指示、无有效错误。这类失败在应用侧几乎无法绕过，只能更换环境。
模拟器排查要点
- 确认模拟器镜像是否包含 VPN 授权组件，缺失时任何配置调整都无效。
- 确认模拟器对 VPN Extension 的支持程度，部分镜像允许安装但不允许启动。
- 在模拟器上先用仅代理模式验证配置，避免把环境缺失误判为配置错误。
- 模拟器结论不能直接外推到真机，反之亦然。
Hey HarmonyOS VPN 连接问题的真机排查
Hey HarmonyOS VPN 连接问题在真机上更多与系统版本、签名与授权状态相关。仓库说明 VPN 闭环仍需更多 HarmonyOS NEXT 真机和系统版本验证，因此单台设备上的失败不等于普遍缺陷，单台设备上的成功也不等于闭环完成。
- 记录设备型号与系统版本，便于判断是否为已验证组合。
- 确认签名与安装方式一致，避免覆盖安装造成授权状态异常。
- 在真机上分别验证仅代理模式与 VPN 模式，定位失败层级。
- 清理残留 Extension 状态后重试，确认停止路径可用。
- 将日志按阶段整理，区分授权失败、启动失败与出站失败。
排查顺序归纳
把上述步骤压缩成一条固定顺序，可以避免在错误层级反复消耗时间。
- 授权：是否有授权请求，系统是否回应，组件是否存在。
- 运行路径：仅代理模式与 VPN 模式分别验证，确认失败落在 Extension 还是 Xray。
- 配置来源：外部深链、系统分享、扫码三个入口是否完成确认并正确保存。
- 模式限制：使用 sing-box 时确认 VPN 模式下只有一个转换后的 outbound。
- 日志：按授权、启停、解析、出站四段读，定位最早失败点。
- 环境差异：模拟器与真机分别下结论，不以一方结果推断另一方。
多数“连接失败”在这一顺序下会收敛到三类原因：授权组件缺失、Extension 启停异常、配置与模式不匹配。先确认授权，再确认路径，最后才动配置。下一步：按第一步检查授权请求是否出现；无请求则转模拟器与镜像排查，有请求则进入日志阶段。
