跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI 生图工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
TypeScript大前端

鸿蒙 WebView 本地资源跨域的客户端处理

鸿蒙 WebView 在加载本地 H5 页面时,内部网络请求可能因 file/resource 协议被 ArkWeb 拦截而出现跨域问题。官方提供了两种处理方式:改用 http/https 并通过 onInterceptRequest 映射本地资源,或使用 setPathAllowingUniversalAccess 放开指定路径的跨域访问。文中采用第二种方案,手动在 src/main/resources 下创建 resfile 目录,将 dist 页面放入其中,再通过 resourceDir 配置允许访问的路径,配合 src 置空和 loadUrl 加载页面,最终在客户端侧解决了混合开发中的跨域访问问题。

热情发布于 2026/6/30更新于 2026/10/962 浏览
鸿蒙 WebView 本地资源跨域的客户端处理

项目背景

在鸿蒙的 H5 混合开发里,Web 组件一旦加载本地页面,内部的网络请求就可能碰到跨域限制。后台如果没配好,这类问题在前端侧会直接炸出来,表现就是资源访问失败。

问题本身

Web 组件本质上还是浏览器内核,浏览器有的跨域限制它也有。官方文档里给了客户端侧的处理方式:解决 Web 组件本地资源跨域问题 - 管理 Web 组件的网络安全与隐私-ArkWeb(方舟 Web)-应用框架 - 华为 HarmonyOS 开发者

为什么会拦截

为了提高安全性,ArkWeb 内核不允许 file 协议或者 resource 协议访问 URL 上下文中来自跨域的请求。因此,在使用 Web 组件加载本地离线资源的时候,Web 组件会拦截 file 协议和 resource 协议的跨域访问。可以通过设置路径列表,再使用 file 协议访问该路径列表中的资源,允许跨域访问本地文件。当 Web 组件无法访问本地跨域资源时,开发者可以在 DevTools 控制台中看到类似以下报错信息。

这段话的意思很直接:你用本地协议加载页面,ArkWeb 就会更严格一些,不会像普通线上页面那样放得很开。

官方给的两种路子

官方文档里其实就两种思路。

第一种是把本地资源换成 http 或 https 协议来加载,再通过 Web 组件的 onInterceptRequest 去拦截和映射本地资源。这个方案更通用,但改动会大一点,适合你本来就愿意把资源访问链路重新整理一遍的场景。

第二种是通过 setPathAllowingUniversalAccess 配一个路径列表。Web 组件用 file 协议访问这些路径下的资源时,可以放开跨域访问。它的限制也写得很清楚:路径必须来自应用文件目录或资源目录对应的子目录,否则会抛 401。空列表则还是按 fileAccess 的规则走。

路径格式大致是这两类:

  • 应用文件目录:通过 Context.filesDir 获取,比如 /data/storage/el2/base/files/example、/data/storage/el2/base/haps/entry/files/example
  • 应用资源目录:通过 Context.resourceDir 获取,比如 /data/storage/el1/bundle/entry/resource/resfile、/data/storage/el1/bundle/entry/resource/resfile/example

我这里怎么做的

这次用的是第二种。原因很简单:改动小,先把页面跑通,比一上来重构资源加载链路省事。

最开始 Web 组件里用的是 resource:// 去读资源:

({ : , : . })
Web
src
'resource://rawfile/dist/index.html#/xxxx'
controller
this
webController

但 setPathAllowingUniversalAccess 需要的是 resourceDir 对应的路径,而项目里默认并不会自动生成 resfile 目录。也就是说,光靠打包是不够的,目录结构得自己补上。

我是在 src/main/resources 下手动新建了 resfile 文件夹,然后把打包后的 dist 目录,也就是 H5 页面文件,放进去。之后资源读取改成这样:

web({ src:'resource://resfile/dist/index.html#/xxxxxxx', controller: this.webController })

真正关键的一步是设置 setPathAllowingUniversalAccess。这里要先把 src 置空,再用 loadUrl 去加载页面,否则权限和加载顺序会拧在一起,排查时很烦。

// 在设置好 setPathAllowingUniversalAccess 之后,需要将 src 置空,使用 loadUrl 加载页面
Web({ src: "", controller: this.webController })
.onControllerAttached(() => {
    try {
        // 设置允许可以跨域访问的路径列表
        this.webController.setPathAllowingUniversalAccess([
            // 这里获取到 resfile 文件目录,后边拼上自己的 h5 文件
            getContext().resourceDir + "/dist/index.html"
        ])
        this.webController.loadUrl('原页面路径')
    } catch (error) {
        console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
    }
})
.javaScriptAccess(true)
.fileAccess(true)
.domStorageAccess(true)

这里的 resourceDir + "/dist/index.html" 要跟你实际放置的文件路径对应上。路径不对,系统直接不给面子,异常会很明确。

结果

按这个方式处理后,鸿蒙 WebView 场景下的 H5 页面跨域问题就能在客户端侧先解决掉。对我来说,这种方案的价值不在于'优雅',而在于它足够直接,适合混合开发里先把页面和请求跑稳定。

目录

  1. 项目背景
  2. 问题本身
  3. 为什么会拦截
  4. 官方给的两种路子
  5. 我这里怎么做的
  6. 结果

更多推荐文章

查看全部
  • MySQL 数据库的基本操作与管理
  • NASA 火星任务软件测试:利用 AIGC 模拟极端环境攻击
  • Python 调用高德地图 MCP 服务查询天气示例
  • C++ 多线程同步实战:互斥锁(mutex)详解
  • 在 MySQL 中查找重复值
  • 使用文心一言设计智能体稳定调用工作流的提示词
  • RoboBrain2.0 具身大脑模型复现:统一感知、推理与规划能力
  • 苍穹外卖实战:SpringTask 定时任务与 WebSocket 实时通信
  • 基于 FPGA 的高性能 PCI 接口设计与实现
  • C++ List 容器实现原理与代码详解(下)
  • 未来考研就业前景最好的十大专业推荐
  • Python Flask RESTful API 开发指南与项目结构模板
  • Java Lambda 和匿名内部类为何不能修改外部变量?final 与等效 final 解析
  • Linux 网络编程基础
  • 通义万相 2.1 模型升级与应用拓展实践
  • 哪些 AI 工具可生成 Word 文档
  • GitHub 热门开源项目日榜 (2025-12-10)
  • Java 中间件:RabbitMQ 延迟队列(死信交换机实现)
  • Linux 倒计时与进度条程序实现及 Plus 升级版本
  • 利用检索增强生成(RAG)降低大模型幻觉与虚假信息

相关免费在线工具

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online

  • Markdown转HTML

    将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online

  • HTML转Markdown

    将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online

  • JSON 压缩

    通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online

  • JSON美化和格式化

    将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online