Hey VPN 排查：连接失败先看哪里

直接给答案：Hey HAP 构建说明的核心是先取回仓库源码，把 build-profile.example.json5 复制为 build-profile.json5，在 DevEco Studio 中配置本机调试或发布签名，再按仓库说明运行 device_vpn_smoke_test.sh build 生成签名 HAP。仓库只提供 ArkTS 源代码，不提供预编译安装包，因此构建必须在本机完成。

Hey HAP 构建说明的适用范围

Hey 是一个用 ArkTS 编写的 HarmonyOS NEXT 应用项目，按 GNU GPL-3.0 发布。它面向 HarmonyOS NEXT，不内置服务器地址、配置源地址、规则集或地区预设，使用前需要用户自行准备这些内容。仓库仅提供源代码，不提供预编译安装包，所以任何可用 HAP 都必须由使用者自行构建。target SDK 与 compatible SDK 以官方仓库当前构建说明为准，不要照搬其他文章里的版本号。

阅读这份 Hey HAP 构建说明前，先确认本机具备 HarmonyOS NEXT 开发环境：DevEco Studio 已安装，HarmonyOS SDK 已下载，命令行工具可用。缺少这些条件，后续签名与构建都无法进行。

源码准备

第一步是取得源码。Hey GitHub 安装说明的起点同样是仓库地址，从 GitHub 克隆项目到本地目录。克隆完成后先不要急着打开构建，先看仓库根目录的 README 与构建相关文件，README 是当前最可靠的依据。

1. 在 GitHub 上找到 Hey 仓库，复制仓库地址。
2. 在本机选择存放代码的目录，执行克隆命令，等待完成。
3. 进入仓库根目录，列出文件，确认存在 build-profile.example.json5 与 device_vpn_smoke_test.sh。
4. 打开 README，逐条阅读构建章节，记录当前要求的 SDK 版本与命令。
5. 把 build-profile.example.json5 复制为 build-profile.json5，不要直接修改带 example 的文件。

README 要求复制 build-profile.example.json5 为 build-profile.json5。build-profile.json5 属于本机配置文件，通常不纳入版本管理，修改前先确认仓库的忽略规则。

复制完成后打开 build-profile.json5，按 README 的说明填写与本机环境对应的字段。target SDK 与 compatible SDK 以官方仓库当前构建说明为准，README 写什么就用什么，不要自行抬高或降低。

Hey DevEco Studio 签名配置

Hey 签名 HAP 构建离不开签名配置。HarmonyOS NEXT 要求 HAP 经过签名才能安装到设备，因此必须在 DevEco Studio 中配置本机调试签名或发布签名。调试签名适合本机调试，发布签名适合对外分发，两者流程不同但入口一致。

调试签名配置步骤

1. 用 DevEco Studio 打开克隆下来的 Hey 项目根目录，等待工程同步完成。
2. 进入 File 菜单下的 Project Structure，找到 Signing Configs 面板。
3. 勾选自动生成签名，登录已实名的开发者账号，让工具生成调试证书与 Profile。
4. 确认签名配置已绑定到当前模块，保存设置。
5. 回到工程视图，检查 build-profile.json5 中的签名段是否与工具写入的内容一致。

发布签名配置步骤

1. 在 DevEco Studio 中创建或导入发布证书、Profile 文件，密钥库格式与密码按工具提示填写。
2. 在 Signing Configs 面板选择手动配置，逐项填入证书路径、Profile 路径、密钥库路径与别名。
3. 保存后执行一次同步，确认没有签名相关报错。
4. 发布签名所用的证书与 Profile 必须匹配同一应用标识，标识不一致会导致安装失败。

签名材料属于敏感文件，不要提交到公开仓库，也不要放进构建产物的分发目录。密钥库密码与别名按本机安全习惯保管。

Hey DevEco Studio 签名配置完成后，构建产出的 HAP 才具备安装条件。若只做本机调试，调试签名足够；若要分发给其他设备，必须使用发布签名，并确保目标设备信任对应证书。

构建签名 HAP

仓库说明中给出的构建入口是 device_vpn_smoke_test.sh build。该脚本会根据传入参数执行构建流程，build 表示构建签名 HAP。执行前确认脚本具备可执行权限，终端位于仓库根目录。

1. 打开终端，切换到 Hey 仓库根目录。
2. 确认 build-profile.json5 已存在且内容完整，签名配置已写入。
3. 为脚本添加可执行权限，避免因权限不足中断。
4. 运行 device_vpn_smoke_test.sh build，观察输出日志。
5. 构建结束后在输出目录查找 HAP 文件，记录文件名与路径。

可按说明运行 device_vpn_smoke_test.sh build 构建签名 HAP。命令与参数以 README 当前写法为准，不要自行拼接未记录的子命令。

构建过程中不要同时修改 build-profile.json5 或签名配置，否则容易出现配置与产物不一致。构建成功后保留完整日志，后续排查问题时日志是第一手材料。

安装前检查

拿到 HAP 不等于可以安装。安装前逐项检查，能减少大量无效重试。

1. 确认设备系统为 HarmonyOS NEXT，且系统版本满足 compatible SDK 要求。
2. 确认 HAP 使用的签名与设备信任链匹配，调试签名需设备处于调试授权状态。
3. 确认应用标识与签名 Profile 中的应用标识一致。
4. 确认 HAP 来自本次构建输出，而不是旧产物或他人转发的文件。
5. 确认已了解该应用不内置服务器地址、配置源地址、规则集或地区预设，首次启动需要自行填入。

安装可通过 DevEco Studio 的运行按钮，也可使用命令行工具安装。无论哪种方式，失败时先看错误码与提示文本，再回到签名与版本两个方向排查。

遇到失败时查看什么

构建或安装失败时，按以下顺序定位，不要盲目重装环境。

构建阶段失败

1. 看日志末尾的第一条错误，而不是最后一屏输出。
2. 检查 build-profile.json5 是否由 example 正确复制而来，字段是否缺失或拼写错误。
3. 检查 SDK 版本是否与 README 要求一致，target SDK 与 compatible SDK 是否被改动。
4. 检查签名配置是否完整，证书、Profile、密钥库路径是否有效。
5. 检查脚本是否具备可执行权限，终端是否位于仓库根目录。

安装阶段失败

1. 看设备返回的错误码，区分签名不匹配、版本不满足、应用标识冲突。
2. 确认设备已开启调试授权，调试签名场景下尤其重要。
3. 确认 HAP 与设备架构、系统版本匹配。
4. 卸载同标识的旧版本后再安装，排除残留数据干扰。

运行阶段异常

1. 确认已按应用要求填入服务器地址或配置源地址，该项目不内置任何地址。
2. 查看设备日志中应用进程的输出，定位初始化失败的位置。
3. 回到 README 确认是否有额外的前置条件说明。

仓库仅提供源代码，不提供预编译安装包。任何声称现成可用的 HAP 都不属于仓库产物，使用前需自行判断来源与完整性。

这份 Hey HAP 构建说明的关键点可以归纳为四件事：源码来自 GitHub 仓库，配置文件由 build-profile.example.json5 复制而来，签名在 DevEco Studio 中完成，构建命令是 device_vpn_smoke_test.sh build。Hey GitHub 安装说明与 Hey 签名 HAP 构建的差别只在于前者强调取源码，后者强调签名与产物。把四件事按顺序做完，再按安装前检查逐项确认，多数问题可以在本机闭环解决。target SDK 与 compatible SDK 始终以官方仓库当前构建说明为准，README 更新后应重新阅读构建章节，不要沿用旧记录。

Hey VPN 排查的最后一步

当真机授权已经出现、配置也能在列表中看到，但连接仍然回落到未连接状态时，可以把问题拆成三段：内核是否启动，HarmonyOS VPN Extension 是否保持运行，以及当前模式是否覆盖了你要访问的流量。先看日志再切换模式，每次只改一个条件，才能知道哪一步带来了变化。

如果从仅代理模式切换到 VPN 模式，系统授权提示可能再次出现；如果改回 Xray，运行时配置也会重新生成。把这些变化连同导入格式写在同一份记录里，排查会比反复重装更快。模拟器缺少 VPN 授权组件时，不要把失败现象归因于订阅内容，先按官方已知限制换到 HarmonyOS NEXT 真机。