# ArkWeb 手记 03｜本地资源加载与 $rawfile 路径踩坑

前面 01 讲了页面加载、生命周期，02 搞定了原生和 H5 双向 JS 通信。现在你大概率会遇到这个头疼问题：

把 HTML、图片、js、css 放进工程，用 ArkWeb 加载本地页面，图片、静态资源直接 404。我当初在 HarmonyOS7 里踩这个坑，来回改相对路径、绝对路径，折腾很久才理清$rawfile的规则。

很多人直接按网页老习惯写 ./image.png，放到鸿蒙工程里直接失效。核心误区：ArkWeb 读取 rawfile 资源，不是普通 web 的文件目录逻辑，它有一套独立的资源映射规则。

核心概念一句话讲清

$rawfile目录专门放不需要编译的静态文件（html、图片、js、css）。ArkWeb 加载$rawfile("index.html")时，H5 内部引用资源，不能直接写相对路径，必须用rawfile://协议。

类比：rawfile 就像一个单独的压缩资源包，H5 页面在这个包里，访问包里其他文件，要用它专属的协议地址，不是本地电脑文件夹那种相对寻址。
前置条件：HarmonyOS7，DevEco Studio，沿用 02 的工程。

第一步：工程目录结构

复制代码

entry/src/main/rawfile/
├─ index.html
├─ css/
│  └─ style.css
├─ js/
│  └─ util.js
└─ img/
   └─ logo.png

注意：rawfile 文件夹不能大写名字，不能嵌套太深，文件名不要中文、空格、特殊符号，极易偶发加载失败。

第二步：ArkTS 加载本地 rawfile 页面

复制代码

import { ArkWeb, ArkWebController } from '@kit.ArkWeb';

@Entry
@Component
struct WebRawFileDemo {
  controller: ArkWebController = new ArkWebController();

  aboutToAppear() {
    this.controller.javascriptEnabled = true;
  }

  build() {
    Column() {
      ArkWeb({
        // 加载rawfile根目录下的index.html
        src: $rawfile("index.html"),
        controller: this.controller
      })
      .width('100%')
      .layoutWeight(1)
    }
  }
}

关键语句拆解：

$rawfile("index.html")：定位 rawfile 根目录下的 html 文件。
这里 src 只写页面入口，H5 内部的图片、css 不能直接写img/logo.png，这就是 90% 人踩的坑。

第三步：H5 页面 index.html 正确写法

复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <!-- 引用rawfile内css，必须 rawfile:// 协议 -->
  <link rel="stylesheet" href="rawfile://css/style.css">
</head>
<body>
  <!-- 图片资源，rawfile:// + 文件路径 -->
  <img src="rawfile://img/logo.png" alt="logo">
  <script src="rawfile://js/util.js"></script>
</body>
</html>

✅ 正确：rawfile://img/logo.png

❌ 错误写法：./img/logo.png / /img/logo.png

第四步：测试流程 & 预期效果

确认所有静态资源放到 entry/src/main/rawfile 下面，目录结构和上面一致。
DevEco 编译，启动模拟器。
页面正常渲染，样式生效，图片正常展示。
如果图片空白，打开 ArkWeb 调试控制台，看资源加载日志，大概率路径写错。

高频踩坑清单（重点）

❌ 资源文件夹名字带中文，图片随机加载失败。
✅ 全部英文小写命名。
❌ rawfile 里面多层嵌套太深，超过 3 层，部分低版本模拟器加载异常。
✅ 尽量控制层级，不超过 2 层。
❌ 把资源放到 resources/base/media，想用 $media 引用。
✅ media 目录适合原生组件图片，ArkWeb H5 静态资源统一放 rawfile。
❌ 混淆远程网页和本地 rawfile 网页的路径规则。

远程 https 页面用普通相对路径；只有$rawfile本地页面，内部资源才需要rawfile://协议头。

❌ 修改静态 html/css 后，直接点刷新模拟器，资源不更新。
✅ rawfile 资源改动后，必须重新 build 项目，增量编译有时候不会更新 rawfile 文件。

小扩展：怎么调试 ArkWeb 资源加载

开启 web 调试，在模拟器上看控制台，能直接看到哪些静态文件请求失败，快速定位路径问题。

复制代码

// 开启调试，仅开发环境用，上线记得删掉
this.controller.webDebuggingAccess = true;

打开 DevTools 就能看到哪些静态文件请求失败。