鸿蒙OS VPN权限：module.json5中权限的注释最佳实践

事情要从上周说起。我接了一个外包项目——给一个叫“CryptoVault”的虚拟币钱包做鸿蒙OS原生适配。客户是个在迪拜做矿场的华人老板，说话带着浓重的福建口音，电话里反复强调：“小张啊，这个VPN权限一定要稳，用户要是连不上节点提不了币，我们一天要亏几十万美金。”

我当时满口答应，心想不就是个VPN权限嘛，Android上写过几百遍了。结果真到了鸿蒙OS上调试，第一天就栽了个大跟头。

那个让我失眠的“Permission denied”

测试机是华为Mate 60 Pro，系统版本HarmonyOS 4.0。我写了个简单的VPN服务，继承自VpnService，在module.json5里按照官方文档加上了权限声明：

json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.VPN" } ] } }

代码逻辑很简单：用户点击“连接矿池节点”按钮，启动VPN隧道，然后通过加密通道把交易数据发到新加坡的服务器。我自信满满地点击了运行——结果应用直接闪退。打开日志一看，核心错误只有一行：

E CORE: Permission denied: cannot establish VPN tunnel without proper configuration

我反复检查了权限声明，没问题啊。又去翻华为开发者文档，才发现一个让我血压升高的细节：鸿蒙OS的VPN权限不仅要声明，还要在代码运行时动态校验，并且校验的API参数名和Android完全不同。

虚拟币场景下的权限校验陷阱

这里我必须插一句，虚拟币钱包对VPN权限的要求比普通应用苛刻得多。普通社交软件断个VPN大不了刷不出图片，但钱包应用如果VPN连接失败，可能导致：

1. 交易签名超时：用户输入的助记词已经生成签名，但网络不通导致交易广播失败，资金可能被锁在内存池
2. 节点同步中断：矿池的实时算力数据无法更新，用户以为还在挖矿，实际已经掉线半小时
3. DNS劫持风险：如果VPN隧道建立不完整，DNS查询走了明文通道，用户的交易地址可能被中间人篡改

我那个福建客户之前就遇到过：他的一个用户连接矿池时，因为VPN权限没处理好，DNS被劫持到了钓鱼节点，结果一笔50个ETH的交易转到了黑客地址。虽然最后通过链上追踪追回了部分资金，但用户的信任感彻底崩了。

深入module.json5的权限迷宫

回到技术层面。在鸿蒙OS上，module.json5的权限声明比Android的AndroidManifest.xml更讲究层级关系。我花了三天时间，翻遍了华为官方论坛、GitHub上的开源项目，甚至去鸿蒙开发者社区问了一圈，才搞明白最佳实践。

权限声明的位置和顺序

很多开发者以为只要在requestPermissions数组里写上权限名就行，但虚拟币场景下，权限声明的顺序会影响系统权限弹窗的优先级。鸿蒙OS的权限管理机制是：先声明的权限会被优先处理，如果前面的权限被用户拒绝，后面的权限可能根本不会弹出请求。

我踩过的坑：一开始我把ohos.permission.INTERNET放在第一位，ohos.permission.VPN放在第二位。结果用户点击连接时，系统先弹网络权限请求，用户同意后，VPN权限请求被系统判断为“低优先级”，直接静默拒绝了——连个提示都没有。

最佳实践应该是这样：

json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.VPN", "reason": "Need to establish encrypted tunnel to crypto mining pool nodes for secure transaction broadcasting", "usedScene": { "ability": ["MainAbility", "VpnAbility"], "when": "inuse" } }, { "name": "ohos.permission.INTERNET", "reason": "Required for network communication with blockchain nodes", "usedScene": { "ability": ["MainAbility", "VpnAbility", "BackgroundService"], "when": "always" } } ] } }

注意这里的关键点：VPN权限要放在第一位，并且要指定usedScene里的when为"inuse"——表示只在用户主动操作时才请求。而网络权限可以设为"always"，因为后台同步需要持续联网。

别忽略了“hidden”权限

虚拟币钱包还有一个特殊需求：防止VPN隧道被系统杀掉。鸿蒙OS为了省电，会在后台杀死长时间运行的VPN服务。解决方案是在module.json5里声明一个隐藏权限：

json5 { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING", "reason": "Maintain persistent VPN tunnel for real-time blockchain data synchronization", "usedScene": { "ability": ["VpnAbility"], "when": "always" } }

这个权限在官方文档里几乎没有提到，是我在华为内部的技术博客里翻到的。加上之后，VPN服务在后台的存活时间从平均15分钟延长到了8小时以上。

权限注释的艺术：写给下一个接手的人

很多开发者觉得注释是写给编译器看的，但在虚拟币项目里，注释是写给“下一个可能接到炸弹的人”看的。我见过一个项目，因为注释写得不清不楚，导致后来者误删了关键权限声明，线上版本直接崩溃，用户资金被锁了整整48小时。

注释要包含“为什么”而不是“是什么”

错误示范：

json5 // VPN权限 { "name": "ohos.permission.VPN" }

正确示范：

json5 /** * VPN权限声明 - 2024年3月15日 * * 为什么需要这个权限： * 1. 建立到新加坡矿池节点（pool.cryptovault.io:443）的加密隧道 * 2. 防止国内运营商对WebSocket连接进行深度包检测（DPI）干扰 * 3. 绕过某些地区对加密货币交易API的DNS污染 * * 注意事项： * - 该权限必须在用户点击“连接矿池”按钮后动态请求，不能在启动时申请 * - 如果用户拒绝，需要降级到普通HTTPS连接，但会弹出风险提示 * - 鸿蒙OS 4.0以下版本不支持该权限的静默获取，必须走系统弹窗 * * 历史修改： * - v1.2.3 新增该权限，解决新加坡节点连接超时问题（工单#2341） * - v1.3.0 添加usedScene配置，修复Android迁移后权限失效问题 */ { "name": "ohos.permission.VPN", "reason": "Establish encrypted tunnel to crypto mining pool nodes", "usedScene": { "ability": ["MainAbility", "VpnAbility"], "when": "inuse" } }

用场景化注释降低认知负荷

虚拟币业务有大量专业术语，如果注释里全是技术名词，新人根本看不懂。我习惯在注释里写“业务场景”：

json5 /** * 后台运行权限 - 2024年6月1日 * * 业务场景： * 用户A在晚上10点启动了ETH挖矿，然后锁屏睡觉。 * 如果没有这个权限，鸿蒙OS会在凌晨3点杀掉VPN服务， * 导致矿池算力数据中断，用户A以为自己还在挖矿， * 实际已经掉线7小时，损失约0.5个ETH（按当前币价约1500美元）。 * * 测试验证： * - 在Mate 60 Pro上锁屏8小时后，VPN隧道依然活跃 * - 在P40上锁屏后，系统会在6小时后强制回收资源，需要实现心跳重连 */ { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING", "reason": "Maintain persistent VPN tunnel for real-time blockchain data synchronization", "usedScene": { "ability": ["VpnAbility"], "when": "always" } }

动态权限校验：别相信系统弹窗

在虚拟币场景下，用户对权限弹窗有天然的警惕性。我遇到过用户连续拒绝三次权限请求，导致系统永久屏蔽弹窗的情况。所以代码里必须做兜底处理。

在VpnAbility里做二次校验

typescript // 在VPN服务的onStart方法里 private checkVpnPermission(): boolean { try { // 鸿蒙OS特有的权限校验API let result = abilityAccessCtrl.createAtManager().verifyAccessToken( bundleInfo.appId, "ohos.permission.VPN" ); if (result !== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { // 记录到日志，方便排查 Logger.error("VPN permission not granted, user may have permanently denied");

  // 弹出自定义对话框，解释为什么需要这个权限   this.showPermissionExplanationDialog();    // 返回false，触发降级逻辑   return false; } return true; 

} catch (error) { // 如果API调用失败，可能是系统版本问题 Logger.error(Permission check failed: ${error.code}, ${error.message}); return false; } }

注释里要写明降级逻辑：

typescript /** * 降级逻辑说明（2024年7月更新）： * * 如果VPN权限被拒绝，进入降级模式： * 1. 使用普通WebSocket连接矿池（无加密隧道） * 2. 在界面上显示黄色警告条：“当前连接未加密，交易数据可能被监控” * 3. 限制单笔交易金额不超过0.1 ETH * 4. 每5分钟弹出一次提示，引导用户去设置里开启VPN权限 * * 注意：降级模式不符合PCI DSS合规要求，不能用于法币交易 */

踩坑实录：那些年我犯过的错

写这篇文章时，我翻出了过去半年的项目日志，整理了几个典型的翻车案例。

案例一：权限声明里的“ability”拼写错误

有一次，我把"ability"写成了"abilities"，鸿蒙OS的解析器直接忽略了整个usedScene配置，导致权限请求时机完全失控。用户一打开应用就弹VPN权限请求，被大量差评。

案例二：忘了处理权限撤销回调

鸿蒙OS允许用户在设置里随时撤销权限。我一开始没监听权限变化事件，结果用户撤销VPN权限后，应用还在尝试建立隧道，导致内存泄漏。后来加上了监听：

typescript // 在MainAbility的onCreate里 this.context.on('permissionChanged', (permissionName: string) => { if (permissionName === 'ohos.permission.VPN') { // 立即断开VPN连接 this.disconnectVpn(); // 弹出提示 prompt.showToast({ message: 'VPN权限已被撤销，请重新授权' }); } });

案例三：虚拟币特有的“矿池节点切换”场景

我们的用户经常需要手动切换矿池节点（比如从ETH矿池切到BTC矿池）。每次切换都要重建VPN隧道。一开始我没在注释里写清楚，新来的同事在切换节点时直接复用了旧隧道的配置，导致新节点的加密握手失败。

后来我在注释里加了详细说明：

json5 /** * 节点切换逻辑 - 2024年8月10日 * * 当用户切换矿池节点时： * 1. 先调用VpnService.disconnect()断开旧隧道 * 2. 清空DNS缓存（防止旧节点的DNS记录干扰） * 3. 重新发起权限校验（因为切换节点可能涉及不同地区的合规要求） * 4. 建立新隧道，使用新节点的证书进行TLS握手 * * 特别注意：BTC矿池的节点使用自签名证书，需要在建立隧道前导入证书链 */

写在最后（但不说“Conclusion”）

现在我的项目已经稳定运行了三个月，那个福建客户很开心，上个月又追加了一个Solana矿池的适配需求。每次新同事加入，我都会把这份module.json5的注释文档发给他们看，告诉他们：“注释不是写给计算机看的，是写给下一个凌晨三点被权限问题折磨得想摔键盘的可怜人的。”

如果你也在做鸿蒙OS上的虚拟币应用，记住：权限声明只是开始，注释才是灵魂。把业务场景写清楚，把踩过的坑记下来，把降级逻辑说明白——这些注释会在某个深夜救你一命，或者救下一个接手你代码的陌生人。

毕竟，在加密货币的世界里，一个权限问题可能就是几万美金的损失。而一行好的注释，可能就是那根救命稻草。