HarmonyOS Next 元服务&应用上架 真机无法显示 web 内容 解决方案

api16

背景

最近，青蓝逐码团队上架的 拾诗纪 HarmonyOS Next 元服务 在 AGC 平台审核时，被退回了，其中有一条原因是这样的

点击我的-用户协议，打开空白

这个问题在 HarmonyOS Next 元服务开发过程中相当常见，特别是当应用需要加载外部网页内容时。本文将详细分析此问题的原因及解决方案，帮助开发者顺利通过审核流程。

问题描述

审核人员在测试我们的应用时，点击了"我的-用户协议"按钮，预期应该打开一个包含用户协议内容的网页，但实际上打开了一个空白页面。这个问题在我们自己的开发环境和模拟器中都没有出现，只在真机测试中显现。

原因

意思是这样的， 在测试的时候，审核人员 用他们的真机打开了我的元服务中的某个页面，然后显示空白。这个页面使用 webview 去加载某个在线网址的，而且自己在本地测试的时候使用模拟器时候发现没有问题。如图所示

HarmonyOS Next 中的 Web 安全机制

HarmonyOS Next 对于 Web 内容的加载实施了严格的安全策略，这是为了保护用户免受潜在的恶意内容攻击。与传统的 Android 或 iOS 相比，HarmonyOS Next 对 WebView 的限制更为严格：

1. 默认禁止加载未授权的外部域名：应用内 WebView 组件默认只能加载已在 AGC 平台声明并验证的域名
2. 模拟器与真机的差异：开发模拟器环境下通常会放宽这些限制，这就是为什么在模拟器中测试正常，而在真机上出现问题
3. 元服务的特殊性：作为 HarmonyOS 生态的重要组成部分，元服务对安全性要求更高

后面经过排查，原因如下：需要在 AGC 平台上，找到你的项目->开发管理->元服务域名管理->域名设置->业务域名 ， 然后添加你元服务中 web 要显示的地址的域名，如图所示

但是这个添加需要有条件，你需要把 配置文件 放到你该域名的根目录下，目的是验证当前的域名所在服务器是你本人的。

详细解决方案

第一步：确认使用的 WebView 配置

在解决问题前，确保你的应用中 WebView 的使用方式正确：

// WebView组件基本使用示例
WebView({
  src: "https://your-domain.com/agreement.html",
  controller: this.controller,
})
  .width("100%")
  .height("100%");

第二步：注册域名并验证所有权

1. 下载配置文件

这里点击直接下载即可，下载后得到文件

配置文件通常是一个以.txt结尾的文本文件，内容包含了特定的验证码，形式如：

harmony-verification=abcde12345xyz

然后使用远程链接工具，把当前文件放到你的服务器域名所在根目录即可。

2. 链接远程服务器

使用 winscp 链接远程服务器

如果你使用的是其他服务器管理工具，如 FileZilla 或者直接通过 SSH 命令行，操作方式类似：

1. 连接到你的 Web 服务器
2. 导航到网站根目录（通常是/var/www/html/或类似路径）
3. 上传验证文件

找到域名所在根目录，然后把刚才的配置文件存放到这里即可

3. 验证文件可访问性

在上传文件后，请确保该文件可以通过以下 URL 访问：

https://your-domain.com/harmony_verification_xxxx.txt

您可以在浏览器中直接访问此 URL 来确认文件已正确上传并可被访问。

4. 在 AGC 平台完成验证

返回 AGC 平台，点击"验证"按钮。系统会尝试访问您上传的验证文件。如果一切正确，验证将通过，您的域名将被添加到白名单中。

验证解决方案

测试效果

最后回到自己的真机上，卸载旧的应用，重新编辑打开，发现有效果了。

为什么需要卸载重装？

卸载重装应用是为了清除可能存在的缓存和旧配置。在 HarmonyOS Next 中，应用的域名白名单信息会在安装时被读取并缓存，因此即使在 AGC 平台更新了配置，已安装的应用也不会立即生效。

常见问题与解决

1. 验证通过后仍然无法显示网页内容

可能的原因：

• 应用未重新安装或重新构建
• 使用的域名与注册的不完全匹配（如使用了子域名但只注册了主域名）
• 网页内容本身存在问题

解决方法：

• 确保重新构建应用并完全卸载旧版本后再安装
• 检查实际使用的 URL 与注册的域名是否完全匹配
• 在浏览器中直接访问网页，确认内容可正常显示

2. 多个域名需要注册

如果你的应用需要访问多个不同域名的网页内容，每个域名都需要单独注册并验证。这是 HarmonyOS Next 的安全要求，无法绕过。

3. 动态 URL 的处理

对于动态生成的 URL，只需注册其基本域名即可。例如，如果你的应用需要访问https://api.example.com/user/1和https://api.example.com/user/2，只需注册api.example.com域名。

总结

在 HarmonyOS Next 元服务开发中，WebView 加载外部内容是一个常见需求，但由于系统的安全限制，需要特别注意域名的注册和验证。本文介绍的解决方案不仅适用于用户协议页面，也适用于所有需要在应用内加载外部网页的场景。

通过正确配置 AGC 平台的域名设置，并验证域名所有权，可以确保你的应用在真机环境中正常显示 Web 内容，顺利通过应用审核。

补充资源

• HarmonyOS Next 开发文档 - WebView 组件
• AGC 平台域名管理指南
• 元服务开发最佳实践

如果你兴趣想要了解更多的鸿蒙应用开发细节和最新资讯，欢迎在评论区留言或者私信或者看我个人信息，可以加入技术交流群。