HarmonyOS Next 元服务&应用上架 真机无法显示 webview 内容 解决方案
HarmonyOS Next 元服务&应用上架 真机无法显示 webview 内容 解决方案
背景
最近，青蓝逐码团队上架的 拾诗纪 HarmonyOS Next 元服务 在 AGC 平台审核时，被退回了，其中有一条原因是这样的
点击我的-用户协议，打开空白
这个问题在 HarmonyOS Next 元服务开发过程中相当常见，特别是当应用需要加载外部网页内容时。本文将详细分析此问题的原因及解决方案，帮助开发者顺利通过审核流程。
问题描述
审核人员在测试我们的应用时，点击了"我的-用户协议"按钮，预期应该打开一个包含用户协议内容的网页，但实际上打开了一个空白页面。这个问题在我们自己的开发环境和模拟器中都没有出现，只在真机测试中显现。
原因
意思是这样的， 在测试的时候，审核人员 用他们的真机打开了我的元服务中的某个页面，然后显示空白。这个页面使用 webview 去加载某个在线网址的，而且自己在本地测试的时候使用模拟器时候发现没有问题。如图所示
HarmonyOS Next 中的 Web 安全机制
HarmonyOS Next 对于 Web 内容的加载实施了严格的安全策略，这是为了保护用户免受潜在的恶意内容攻击。与传统的 Android 或 iOS 相比，HarmonyOS Next 对 WebView 的限制更为严格：
- 默认禁止加载未授权的外部域名：应用内 WebView 组件默认只能加载已在 AGC 平台声明并验证的域名
- 模拟器与真机的差异：开发模拟器环境下通常会放宽这些限制，这就是为什么在模拟器中测试正常，而在真机上出现问题
- 元服务的特殊性：作为 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 命令行，操作方式类似：
- 连接到你的 Web 服务器
- 导航到网站根目录（通常是/var/www/html/或类似路径）
- 上传验证文件
找到域名所在根目录，然后把刚才的配置文件存放到这里即可
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 平台域名管理指南
- 元服务开发最佳实践
如果你兴趣想要了解更多的鸿蒙应用开发细节和最新资讯，欢迎在评论区留言或者私信或者看我个人信息，可以加入技术交流群。
